This article explains how to generate a payment link through an external API, store the returned link in a hidden question, and trigger the API from either Rules or Rating.

Before starting, you should already understand how to configure and test an API request.

See:

• API Builder Overview
• Using the Formula Tester

Overview

The process is:

SchemeServe sends payment details to the provider
                    ↓
The payment provider creates a payment link
                    ↓
The API returns the payment link
                    ↓
SchemeServe saves the link into a hidden question
                    ↓
The link is used in an email, document or customer journey

The exact request and response structure will depend on the payment provider’s API documentation.

Before You Begin

You will need:

• The payment provider’s API documentation.
• The API endpoint used to create payment links.
• The required authentication details.
• A successful payment-link request in Postman or a similar testing tool.
• A test case in SchemeServe.
• The details that must be sent to the provider, such as:
  • payment amount
  • customer name
  • email address
  • policy reference
  • return URL
  • payment description

Always confirm that the provider returns a valid payment link before recreating the request in SchemeServe.

Step 1: Create the Hidden Question(s)

First, create a question to store the payment link returned by the API.

The question should normally be:

• A text question
• Hidden from the customer
• Large enough to store a full URL

Example:

Use a clear and unique question name. This makes it easier to identify when mapping the API response and using the link elsewhere.

You may also require additional hidden questions, depending on the integration.

Examples include:

• PaymentReference
• PaymentStatus
• PaymentProviderTransactionId
• PaymentLinkCreated
• PaymentRequestType

These can be used to store response information or control when the API should run.

Step 2: Build the Payment-Link API

Build the request using the API Builder.

Follow the payment provider’s documentation when configuring:

• Request method
• Endpoint URL
• Headers
• Authentication
• Request body

Payment-link APIs commonly use a POST request because SchemeServe is sending payment details to the provider and asking it to create a new payment session.

For detailed instructions, refer to the API Builder Overview article.

Start with Hardcoded Test Data

When first creating the API, use fixed test values.

For example:

{
  "amount": 125.50,
  "reference": "TEST-001",
  "customerName": "Test Customer",
  "email": "test@example.com"
}

Test the request and confirm that the response contains a valid payment URL.

A response may look similar to:

{
  "paymentId": "PAY-123456",
  "paymentUrl": "https://payments.example.com/pay/PAY-123456",
  "status": "created"
}

The field names will vary between providers.

Step 3: Replace Test Data with SchemeServe Values

Once the hardcoded request works, replace the test values with SchemeServe formulas.

For example:

{
  "amount": "##[TotalPremium]##",
  "reference": "##[Policy.Reference]##",
  "customerName": "##[CustomerName]##",
  "email": "##[EmailAddress]##"
}

The precise question names and system IDs will depend on the scheme.

Use the Formula Tester to verify every dynamic value before adding it to the API request.

This is particularly important for:

• premium values
• policy or case references
• customer names
• email addresses
• inception dates
• return URLs
• encoded system IDs

For instructions, refer to Using the Formula Tester.

Formatting Values

The provider may require values in a specific format.

For example, a date may need to be sent as:

08/07/2026

You could test:

[Policy.InceptionDate].ToString("dd/MM/yyyy")

A provider may also expect the payment amount in:

• pounds, such as 125.50
• pence, such as 12550

Check the API documentation carefully. Sending the amount in the wrong unit could create an incorrect payment request.

Encoding Values

Some values may need to be URL encoded, particularly when they form part of a query string or return URL.

Example:

##[UrlEncode([Policy.Reference])]##

Only encode values when required by the provider or when passing them within a URL. Values in a standard JSON body should not normally be URL encoded unless the documentation specifically requires it.

Step 4: Map the Returned Payment Link

After the request succeeds, configure the API to save the returned payment URL into the hidden question.

For example:

API response field: paymentUrl
              ↓
SchemeServe question: PaymentLink

The exact response location depends on the returned JSON.

For a response such as:

{
  "paymentUrl": "https://payments.example.com/pay/PAY-123456"
}

the value to map is:

paymentUrl

For a nested response such as:

{
  "payment": {
    "url": "https://payments.example.com/pay/PAY-123456"
  }
}

the response path may be similar to:

payment.url

Use the actual response structure provided by the payment provider.

You can also map other useful response values.

After mapping the response, run the API against a test case and confirm that the hidden question contains the full link.

Step 5: Add the API to Rules or Rating

Creating the API does not automatically make it run. It must be added to the appropriate process within the scheme.

The API can normally be triggered through either Rules or Rating.

Triggering the API from Rules

Rules are usually the better option when the payment link should only be generated under specific conditions.

For example:

If Payment Required = Yes
and Payment Link is blank
                    ↓
Run Create Payment Link API

Rules are useful when the API should run based on:

• a customer selection
• a hidden question value
• a particular payment method
• the policy reaching a certain stage
• an internal user action
• a specific workflow condition

A hidden control question can be used to determine which API action should run.

Example:

The Rule can then trigger the relevant API based on the stored value.

Example Rule Logic

IF PaymentMethod = "Online Payment"
AND PaymentLink = ""
THEN Run Payment Link API

Checking whether the payment-link question is blank can help prevent a new link from being generated every time the Rules run.

However, whether a payment link can be reused depends on the provider. Some links may expire or only support a single payment.

Triggering the API from Rating

Rating may be appropriate when the payment link must be generated automatically as part of the quotation or rating process.

For example:

Calculate premium
        ↓
Send final premium to payment API
        ↓
Save returned payment link

Rating is generally more suitable when:

• the API requires the calculated premium
• the API result is needed immediately during quotation
• the request must run whenever the policy is rated

Take care when adding payment-link APIs to Rating. Rating may run multiple times during a customer journey, which could create multiple payment sessions or links.

Before using Rating, confirm:

• whether repeated requests create duplicate payment links
• whether an existing link can be updated
• whether the provider supports an idempotency key
• whether the API should only run when the premium is final

For most payment-link workflows, Rules provide more control over when the request is sent.

Rules or Rating?

The correct option depends on the payment provider and the required customer journey.

Step 6: Use the Payment Link

Once the hidden question contains the payment URL, it can be referenced elsewhere in SchemeServe.

Common uses include:

• adding a Pay Now button to an email
• displaying the link in a document
• showing the link on a customer-facing page
• including it in an internal notification
• passing it to another API

Example HTML link:

<a href="[PaymentLink]">Pay now</a>

Use the correct question token syntax for the area in which the link is being inserted.

Test the final output to ensure the complete URL is being used and that the link opens the correct payment page.

Preventing Duplicate Payment Links

Before generating a new link, consider whether one has already been created.

A Rule could check:

PaymentLink is blank

You may also store:

• the date the link was created
• the provider’s payment ID
• the payment status
• whether the link has expired

Example logic:

IF PaymentLink is blank
OR PaymentStatus = "Expired"
THEN Run Create Payment Link API

The correct logic will depend on how the payment provider handles expiry, completed payments and repeated requests.

Testing the Integration

Test the complete process using a test case.

Confirm that:

1. The API works in Postman.
2. The SchemeServe API request sends the correct values.
3. Each formula returns the expected result in the Formula Tester.
4. The provider returns a payment URL.
5. The URL is saved into the correct hidden question.
6. Rules or Rating trigger the API at the correct time.
7. The API does not run unexpectedly or create duplicate links.
8. The link opens successfully.
9. The payment amount and policy reference are correct.
10. Emails, documents or buttons use the stored link correctly.

Do not test live payments unless the provider has confirmed that the integration is using an appropriate test or sandbox environment.

Troubleshooting

The hidden question remains blank

Check that:

• the API returned a payment link
• the response path is correct
• the response field is mapped to the correct question
• the question exists in the selected scheme
• the API completed successfully

The API works in Postman but not in SchemeServe

Check:

• authentication headers
• endpoint URL
• request-body formatting
• dynamic formula results
• date and amount formats
• quotation marks and brackets
• whether values require encoding

Re-test each dynamic value in the Formula Tester.

Multiple payment links are being created

The API may be running every time Rules or Rating executes.

Consider adding a condition such as:

PaymentLink is blank

You may also need to use a payment reference or idempotency value supported by the provider.

The payment amount is incorrect

Confirm whether the provider expects:

• pounds or pence
• gross premium or net premium
• IPT to be included
• fees to be included
• a decimal or whole-number value

The link is returned but does not open

Check whether:

• the full URL has been saved
• the link has expired
• test and live environments have been mixed
• the URL was incorrectly encoded
• the HTML link uses the correct hidden-question value

Best Practices

• Build and test the request outside SchemeServe first.
• Use the Formula Tester for every dynamic value.
• Begin with hardcoded values and replace them gradually.
• Store payment URLs and provider references in clearly named hidden questions.
• Use Rules where you need precise control over when the API runs.
• Prevent duplicate payment-link requests.
• Confirm the provider’s amount and date formats.
• Test in the provider’s sandbox environment before going live.
• Never expose API keys or authentication credentials in customer-facing content.