Tutorial: Make a single payment using Pay By Link

Pay By Link is available as a Private Beta version. Please contact your Customer Success Manager if you would like to access it.

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.

1. Create a link

Make a request to POST /hosted/payment-requests/links, 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.

Example request:

Copy
Copied
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"
  }
}'

Example response:

Copy
Copied
{
  "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"
  }
}

Store the hostedUrl returned in the response to use in step 2.

2. Send the hostedUrl 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. 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.

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

4. 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} specifying the paymentRequestId in the path.

Example request:

Copy
Copied
curl -L -X GET 'https://api.yapily.com/hosted/payment-requests/{paymentRequestId}' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'

Example response:

Copy
Copied
{
  "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"
        }
      }
    ]
  }
}

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