> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yapily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment tutorial using Yapily Hosted Pages

> Tutorial for initiating a single payment using Yapily Hosted Pages. Generate a payment session URL and guide users through the complete open banking payment journey.

<Note>
  Hosted Pages is available as a [Beta version](/getting-started/overview#yapily-hosted-pages-beta).
  Please contact your Customer Success Manager if you would like to access it.
</Note>

## Introduction

This tutorial explains how to use Yapily Hosted Pages to make a UK domestic single payment.

**Note:** All requests made to the Yapily API require [basic authentication](/getting-started/integration-setup/api-authentication).

***

<Steps>
  <Step title="Create a hosted payment request">
    Make a request to [POST /hosted/payment-requests](/api-reference/hosted-payment-pages/create-hosted-payment-request), including the payment request details, institution country code, redirect URL and user ID.

    You must provide the `institutionIdentifiers.institutionCountryCode` field. This controls the country of the institution the user can pay from.

    In addition, you can optionally provide the ID of a specific institution in `institutionIdentifiers.institutionId` field to only allow payment from this institution. This skips the bank selection screen in the hosted flow.

    You can optionally provide `userSettings` to set the user's preferred language and location.

    <CodeGroup>
      ```bash Request theme={null}
      curl -L -X POST 'https://api.yapily.com/hosted/payment-requests' \
      -H 'Content-Type: application/json' \
      -u 'APPLICATION_KEY:APPLICATION_SECRET' \
      -d '{
        "applicationUserId": "john.doe@company.com",
        "institutionIdentifiers": {
          "institutionCountryCode": "GB"
        },
        "userSettings": {
          "language": "en",
          "location": "GB"
        },
        "redirectUrl": "https://tpp-application.com/",
        "paymentRequestDetails": {
          "paymentIdempotencyId": "4289457hd38djoa783jw9qag3",
          "amountDetails": {
            "amountToPay": 10,
            "currency": "GBP"
          },
          "reference": "Test Payment",
          "type": "DOMESTIC_PAYMENT",
          "payee": {
            "name": "Jane Doe",
            "accountIdentifications": [
              {
                "type": "SORT_CODE",
                "identification": "123456"
              },
              {
                "type": "ACCOUNT_NUMBER",
                "identification": "12345678"
              }
            ]
          }
        }
      }'
      ```

      ```json Response theme={null}
      {
        "meta": {
          "tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
        },
        "data": {
          "paymentRequestId": "eb39f8ae-aeff-4ffa-a23d-d4a5b3eff406",
          "userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
          "applicationUserId": "john.doe@company.com",
          "applicationId": "64949de6-6510-4d70-9500-d4aa094c506c",
          "institutionIdentifiers": {
            "institutionId": "modelo-sandbox",
            "institutionCountryCode": "GB"
          },
          "userSettings": {
            "language": "en",
            "location": "GB"
          },
          "redirectUrl": "https://tpp-application.com/",
          "paymentRequestDetails": {
            "paymentIdempotencyId": "4289457hd38djoa783jw9qag3",
            "amountDetails": {
              "amountToPay": 1,
              "currency": "GBP"
            },
            "reference": "Test Payment",
            "contextType": "OTHER",
            "type": "DOMESTIC_PAYMENT",
            "payee": {
              "name": "Jane Doe",
              "accountIdentifications": [
                {
                  "type": "SORT_CODE",
                  "identification": "123456"
                },
                {
                  "type": "ACCOUNT_NUMBER",
                  "identification": "12345678"
                }
              ]
            }
          },
          "hostedUrl": "https://prototypes.yapily.com/auth-link1.html",
          "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
          "createdAt": "2021-06-10T11:26:54.887Z",
          "authorisationExpiresAt": "2021-06-10T11:36:54.887Z",
          "status": "ACTIVE"
        }
      }
      ```
    </CodeGroup>

    Store the `hostedUrl` returned in the response to use in step 2.
  </Step>

  <Step title="Redirect the user to the hosted URL">
    Redirect the end user from your application to the Yapily Hosted Pages URL. This initiates the user journey for the payment request.
  </Step>

  <Step title="End user completes the payment flow">
    The end user follows the Yapily hosted screens to complete the payment request.

    A typical journey includes bank selection, redirection to their chosen bank, payment initiation confirmation and redirection back to your application.

    See [UI screens](/tools-and-services/hosted-pages/ui-screens) for more details.

    The user will be automatically redirected to the `redirectUrl` specified in the initial payment request in Step 1 once the payment flow is complete. We recommend you redirect the user back to your application to create a good user experience.

    The `paymentRequestId` is returned as part of the `redirectUrl`. You can use this to check the status of the payment in step 4.
  </Step>

  <Step title="Retrieve details of the payment request">
    On an end user's completion of the hosted pages flow, you should check the payment status to confirm the payment has initiated successfully before proceeding with any further actions.

    You can retrieve details of the payment request using [GET /hosted/payment-requests/{paymentRequestId}](/api-reference/hosted-payment-pages/get-hosted-payment-request) specifying the `paymentRequestId` in the path.

    <CodeGroup>
      ```bash Request theme={null}
      curl -L -X GET 'https://api.yapily.com/hosted/payment-requests/{paymentRequestId}' \
      -H 'Content-Type: application/json' \
      -u 'APPLICATION_KEY:APPLICATION_SECRET'
      ```

      ```json Response theme={null}
      {
        "meta": {
          "tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
        },
        "data": {
          "paymentRequestId": "eb39f8ae-aeff-4ffa-a23d-d4a5b3eff406",
          "userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
          "applicationUserId": "john.doe@company.com",
          "applicationId": "64949de6-6510-4d70-9500-d4aa094c506c",
          "institutionIdentifiers": {
            "institutionId": "modelo-sandbox",
            "institutionCountryCode": "GB"
          },
          "userSettings": {
            "language": "en",
            "location": "GB"
          },
          "redirectUrl": "https://tpp-application.com/",
          "paymentRequestDetails": {
            "amountDetails": {
              "amountToPay": 1,
              "currency": "GBP"
            },
            "reference": "Test Payment",
            "contextType": "OTHER",
            "type": "DOMESTIC_PAYMENT",
            "payee": {
              "name": "Jane Doe",
              "accountIdentifications": [
                {
                  "type": "SORT_CODE",
                  "identification": "123456"
                },
                {
                  "type": "ACCOUNT_NUMBER",
                  "identification": "12345678"
                }
              ]
            }
          },
          "createdAt": "2021-06-10T11:26:54.887Z",
          "authorisationExpiresAt": "2021-06-10T11:36:54.887Z",
          "status": "ACTIVE",
          "payments": [
            {
              "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
              "institutionIdentifiers": {
                "institutionId": "string",
                "institutionCountryCode": "GB"
              },
              "phases": [
                {
                  "phaseName": "INITIATED",
                  "phaseCreatedAt": "2021-06-10T11:26:54.887Z"
                },
                {
                  "phaseName": "INSTITUTION_SUBMITTED",
                  "phaseCreatedAt": "2021-06-10T11:26:55.123Z"
                },
                {
                  "phaseName": "AUTHORISATION_INITIATED",
                  "phaseCreatedAt": "2021-06-10T11:27:05.123Z"
                },
                {
                  "phaseName": "VALIDATION_COMPLETED",
                  "phaseCreatedAt": "2021-06-10T11:27:05.223Z"
                },
                {
                  "phaseName": "AUTHORISATION_CREATED",
                  "phaseCreatedAt": "2021-06-10T11:27:06.637Z"
                },
                {
                  "phaseName": "AUTHORISED",
                  "phaseCreatedAt": "2021-06-10T11:27:10.637Z"
                },
                {
                  "phaseName": "SUBMITTED",
                  "phaseCreatedAt": "2021-06-10T11:27:10.654Z"
                },
                {
                  "phaseName": "ACCEPTED",
                  "phaseCreatedAt": "2021-06-10T11:27:11.867Z"
                },
                {
                  "phaseName": "SETTLEMENT_COMPLETED",
                  "phaseCreatedAt": "2021-06-10T11:27:13.887Z"
                }
              ],
              "paymentStatus": "COMPLETED",
              "statusDetails": [
                {
                  "status": "PENDING",
                  "statusUpdateDate": "2021-06-10T11:27:11.867Z",
                  "isoStatus": {
                    "code": "PDNG",
                    "name": "Pending"
                  }
                },
                {
                  "status": "COMPLETED",
                  "statusUpdateDate": "2021-06-10T11:27:13.887Z",
                  "isoStatus": {
                    "code": "ACSC",
                    "name": "AcceptedSettlementCompleted"
                  }
                }
              ],
              "institutionPaymentId": "string",
              "paymentLifecycleId": "string",
              "paymentIdempotencyId": "04ab4536gaerfc0e1f93c4f4",
              "reference": "Bill payment",
              "contextType": "OTHER",
              "type": "DOMESTIC_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"
                }
              },
              "amount": {
                "amount": 10,
                "currency": "GBP"
              }
            }
          ]
        }
      }
      ```
    </CodeGroup>

    ### Monitoring Payment Status

    <Tip>
      We recommend using [webhooks](/tools-and-services/hosted-pages/payment-webhooks) to receive real-time notifications when your payment completes or fails. This provides:

      * **Immediate status updates** - No polling delay
      * **Reduced API calls** - Cost savings for both parties
      * **Better user experience** - Faster feedback to customers
    </Tip>

    <Accordion title="Alternative: Poll for status updates">
      If you cannot use webhooks, you can monitor the payment status by repeatedly calling the GET endpoint above until the `paymentStatus` field transitions to `COMPLETED` or `FAILED`.

      **Note:** Polling increases API usage and may delay status updates compared to webhooks.
    </Accordion>
  </Step>
</Steps>