> ## 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 Pay By Link

> Tutorial for creating and sharing a Yapily Pay By Link payment request. Generate a payment link, customise parameters, share with payers, and track payment status.

<Note>
  Pay By Link is available as a [Private Beta version](/getting-started/overview#private-beta).
  Please contact your Customer Success Manager if you would like to access it.
</Note>

## Introduction

This tutorial explains how to use Pay By Link 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 payment link">
    Make a request to [POST /hosted/payment-requests/links](/api-reference/hosted-payment-pages/create-pay-by-link), 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 the due date of the payment `paymentRequestDetails.paymentDueDate`. If provided, this is displayed to the user on the landing page after clicking the link.

    You can optionally provide the link expiry date, `authorisationExpiresAt`. The value can be up to 30 days in the future. If not provided, the expiry date defaults to 7 days.

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

    <CodeGroup>
      ```bash Request theme={null}
      curl -L -X GET 'https://api.yapily.com/hosted/payment-requests/links' \
      -H 'Content-Type: application/json' \
      -u 'APPLICATION_KEY:APPLICATION_SECRET' \
      -d '{
        "userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
        "applicationUserId": "john.doe@company.com",
        "institutionIdentifiers": {
          "institutionCountryCode": "GB"
        },
        "userSettings": {
          "language": "en",
          "location": "GB"
        },
        "redirectUrl": "https://tpp-application.com/",
        "authorisationExpiresAt": "28-07-2022 21:05:00",
        "paymentRequestDetails": {
          "amountDetails": {
            "amountToPay": 1,
            "currency": "GBP"
          },
          "reference": "Test Payment",
          "type": "DOMESTIC_PAYMENT",
          "payee": {
            "name": "Jane Doe",
            "accountIdentifications": [
              {
                "type": "SORT_CODE",
                "identification": "123456"
              },
              {
                "type": "ACCOUNT_NUMBER",
                "identification": "12345678"
              }
            ]
          },
          "paymentDueDate": "28-07-2022"
        }
      }'
      ```

      ```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": 10,
              "currency": "GBP"
            },
            "reference": "Test Payment",
            "contextType": "OTHER",
            "type": "DOMESTIC_PAYMENT",
            "paymentDueDate": "28-07-2022",
            "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="Send the hosted URL link to the user">
    Send the hostedUrl link to the end user, for example via email or SMS.

    The link is single use for a fixed payment amount and will expire at the date specified in the request in Step 1, or if not specified, after 7 days.

    Once the user clicks the link they are redirected to the [Yapily Hosted Pages landing page](/tools-and-services/pay-by-link/ui-screens#landing-page). The landing page confirms the payment details and allows the user to 'Pay by bank'.

    Once the user selects 'Pay by bank' they proceed to complete the payment flow.
  </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"
                }
              ],
              "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>

    In addition, we recommend you continue to monitor the payment status until the status transitions to COMPLETED indicating the payment has been processed successfully.
  </Step>
</Steps>