Tutorial: Make a single payment using Yapily Hosted Pages

Hosted Pages 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 Yapily Hosted Pages to make a UK domestic single payment.

Note: All requests made to the Yapily API require basic authentication.

1. Create a hosted payment request

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

Example request:

Copy
Copied
curl -L -X GET '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"
        }
      ]
    }
  }
}'

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": {
      "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"
  }
}

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

2. Redirect the user to the hostedUrl

Redirect the end user from your application to the Yapily Hosted Pages URL. This initiates the user journey for the payment request.

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"
          }
        ],
        "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"
        }
      }
    ]
  }
}

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