Skip to main content
Create Hosted payment request
curl --request POST \
  --url https://api.yapily.com/hosted/payment-requests \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json;charset=UTF-8' \
  --data '
{
  "userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
  "applicationUserId": "string",
  "institutionIdentifiers": {
    "institutionId": "modelo-sandbox",
    "institutionCountryCode": "GB"
  },
  "userSettings": {
    "language": "en",
    "location": "GB"
  },
  "redirectUrl": "https://tpp-application.com/",
  "paymentRequestDetails": {
    "paymentIdempotencyId": "4289457hd38djoa783jw9qag3",
    "amountDetails": {
      "amountToPay": 10,
      "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"
        }
      ]
    },
    "payer": {
      "name": "John Doe",
      "accountIdentifications": [
        {
          "type": "SORT_CODE",
          "identification": "121212"
        },
        {
          "type": "ACCOUNT_NUMBER",
          "identification": "87654321"
        }
      ]
    }
  }
}
'
import requests

url = "https://api.yapily.com/hosted/payment-requests"

payload = {
    "userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
    "applicationUserId": "string",
    "institutionIdentifiers": {
        "institutionId": "modelo-sandbox",
        "institutionCountryCode": "GB"
    },
    "userSettings": {
        "language": "en",
        "location": "GB"
    },
    "redirectUrl": "https://tpp-application.com/",
    "paymentRequestDetails": {
        "paymentIdempotencyId": "4289457hd38djoa783jw9qag3",
        "amountDetails": {
            "amountToPay": 10,
            "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"
                }
            ]
        },
        "payer": {
            "name": "John Doe",
            "accountIdentifications": [
                {
                    "type": "SORT_CODE",
                    "identification": "121212"
                },
                {
                    "type": "ACCOUNT_NUMBER",
                    "identification": "87654321"
                }
            ]
        }
    }
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json;charset=UTF-8"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json;charset=UTF-8'
  },
  body: JSON.stringify({
    userId: '3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d',
    applicationUserId: 'string',
    institutionIdentifiers: {institutionId: 'modelo-sandbox', institutionCountryCode: 'GB'},
    userSettings: {language: 'en', location: 'GB'},
    redirectUrl: 'https://tpp-application.com/',
    paymentRequestDetails: {
      paymentIdempotencyId: '4289457hd38djoa783jw9qag3',
      amountDetails: {amountToPay: 10, 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'}
        ]
      },
      payer: {
        name: 'John Doe',
        accountIdentifications: [
          {type: 'SORT_CODE', identification: '121212'},
          {type: 'ACCOUNT_NUMBER', identification: '87654321'}
        ]
      }
    }
  })
};

fetch('https://api.yapily.com/hosted/payment-requests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.yapily.com/hosted/payment-requests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => '3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d',
    'applicationUserId' => 'string',
    'institutionIdentifiers' => [
        'institutionId' => 'modelo-sandbox',
        'institutionCountryCode' => 'GB'
    ],
    'userSettings' => [
        'language' => 'en',
        'location' => 'GB'
    ],
    'redirectUrl' => 'https://tpp-application.com/',
    'paymentRequestDetails' => [
        'paymentIdempotencyId' => '4289457hd38djoa783jw9qag3',
        'amountDetails' => [
                'amountToPay' => 10,
                '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'
                                ]
                ]
        ],
        'payer' => [
                'name' => 'John Doe',
                'accountIdentifications' => [
                                [
                                                                'type' => 'SORT_CODE',
                                                                'identification' => '121212'
                                ],
                                [
                                                                'type' => 'ACCOUNT_NUMBER',
                                                                'identification' => '87654321'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json;charset=UTF-8"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.yapily.com/hosted/payment-requests"

	payload := strings.NewReader("{\n  \"userId\": \"3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d\",\n  \"applicationUserId\": \"string\",\n  \"institutionIdentifiers\": {\n    \"institutionId\": \"modelo-sandbox\",\n    \"institutionCountryCode\": \"GB\"\n  },\n  \"userSettings\": {\n    \"language\": \"en\",\n    \"location\": \"GB\"\n  },\n  \"redirectUrl\": \"https://tpp-application.com/\",\n  \"paymentRequestDetails\": {\n    \"paymentIdempotencyId\": \"4289457hd38djoa783jw9qag3\",\n    \"amountDetails\": {\n      \"amountToPay\": 10,\n      \"currency\": \"GBP\"\n    },\n    \"reference\": \"Test Payment\",\n    \"contextType\": \"OTHER\",\n    \"type\": \"DOMESTIC_PAYMENT\",\n    \"payee\": {\n      \"name\": \"Jane Doe\",\n      \"accountIdentifications\": [\n        {\n          \"type\": \"SORT_CODE\",\n          \"identification\": \"123456\"\n        },\n        {\n          \"type\": \"ACCOUNT_NUMBER\",\n          \"identification\": \"12345678\"\n        }\n      ]\n    },\n    \"payer\": {\n      \"name\": \"John Doe\",\n      \"accountIdentifications\": [\n        {\n          \"type\": \"SORT_CODE\",\n          \"identification\": \"121212\"\n        },\n        {\n          \"type\": \"ACCOUNT_NUMBER\",\n          \"identification\": \"87654321\"\n        }\n      ]\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json;charset=UTF-8")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.yapily.com/hosted/payment-requests")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json;charset=UTF-8")
  .body("{\n  \"userId\": \"3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d\",\n  \"applicationUserId\": \"string\",\n  \"institutionIdentifiers\": {\n    \"institutionId\": \"modelo-sandbox\",\n    \"institutionCountryCode\": \"GB\"\n  },\n  \"userSettings\": {\n    \"language\": \"en\",\n    \"location\": \"GB\"\n  },\n  \"redirectUrl\": \"https://tpp-application.com/\",\n  \"paymentRequestDetails\": {\n    \"paymentIdempotencyId\": \"4289457hd38djoa783jw9qag3\",\n    \"amountDetails\": {\n      \"amountToPay\": 10,\n      \"currency\": \"GBP\"\n    },\n    \"reference\": \"Test Payment\",\n    \"contextType\": \"OTHER\",\n    \"type\": \"DOMESTIC_PAYMENT\",\n    \"payee\": {\n      \"name\": \"Jane Doe\",\n      \"accountIdentifications\": [\n        {\n          \"type\": \"SORT_CODE\",\n          \"identification\": \"123456\"\n        },\n        {\n          \"type\": \"ACCOUNT_NUMBER\",\n          \"identification\": \"12345678\"\n        }\n      ]\n    },\n    \"payer\": {\n      \"name\": \"John Doe\",\n      \"accountIdentifications\": [\n        {\n          \"type\": \"SORT_CODE\",\n          \"identification\": \"121212\"\n        },\n        {\n          \"type\": \"ACCOUNT_NUMBER\",\n          \"identification\": \"87654321\"\n        }\n      ]\n    }\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.yapily.com/hosted/payment-requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json;charset=UTF-8'
request.body = "{\n  \"userId\": \"3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d\",\n  \"applicationUserId\": \"string\",\n  \"institutionIdentifiers\": {\n    \"institutionId\": \"modelo-sandbox\",\n    \"institutionCountryCode\": \"GB\"\n  },\n  \"userSettings\": {\n    \"language\": \"en\",\n    \"location\": \"GB\"\n  },\n  \"redirectUrl\": \"https://tpp-application.com/\",\n  \"paymentRequestDetails\": {\n    \"paymentIdempotencyId\": \"4289457hd38djoa783jw9qag3\",\n    \"amountDetails\": {\n      \"amountToPay\": 10,\n      \"currency\": \"GBP\"\n    },\n    \"reference\": \"Test Payment\",\n    \"contextType\": \"OTHER\",\n    \"type\": \"DOMESTIC_PAYMENT\",\n    \"payee\": {\n      \"name\": \"Jane Doe\",\n      \"accountIdentifications\": [\n        {\n          \"type\": \"SORT_CODE\",\n          \"identification\": \"123456\"\n        },\n        {\n          \"type\": \"ACCOUNT_NUMBER\",\n          \"identification\": \"12345678\"\n        }\n      ]\n    },\n    \"payer\": {\n      \"name\": \"John Doe\",\n      \"accountIdentifications\": [\n        {\n          \"type\": \"SORT_CODE\",\n          \"identification\": \"121212\"\n        },\n        {\n          \"type\": \"ACCOUNT_NUMBER\",\n          \"identification\": \"87654321\"\n        }\n      ]\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "meta": {
    "tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
  },
  "data": {
    "paymentRequestId": "eb39f8ae-aeff-4ffa-a23d-d4a5b3eff406",
    "userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
    "applicationUserId": "string",
    "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"
          }
        ]
      },
      "payer": {
        "name": "John Doe",
        "accountIdentifications": [
          {
            "type": "SORT_CODE",
            "identification": "121212"
          },
          {
            "type": "ACCOUNT_NUMBER",
            "identification": "87654321"
          }
        ]
      }
    },
    "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"
  }
}
{
  "error": {
    "tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154",
    "code": 400,
    "status": "BAD_REQUEST",
    "supportUrl": "https://support.yapily.com/",
    "source": "YAPILY",
    "issues": [
      {
        "type": "BAD_REQUEST",
        "code": 10600,
        "message": "The server could not understand the request due to invalid syntax"
      }
    ]
  }
}
{
  "error": {
    "tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154",
    "code": 401,
    "status": "UNAUTHORIZED",
    "supportUrl": "https://support.yapily.com/",
    "source": "YAPILY",
    "issues": [
      {
        "type": "CREDENTIALS",
        "code": 10700,
        "message": "Authorization header invalid or credentials not authenticated"
      }
    ]
  }
}
{
  "error": {
    "tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154",
    "code": 500,
    "status": "INTERNAL SERVER ERROR",
    "supportUrl": "https://support.yapily.com/",
    "source": "YAPILY",
    "issues": [
      {
        "type": "INTERNAL_SERVER_ERROR",
        "code": 11000,
        "message": "Unexpected server error"
      }
    ]
  }
}
{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}
Learn more: Hosted Payment Pages

Authorizations

​
Authorization
string
header
required

Use HTTP Basic Authentication with your Application ID as username and Application Secret as password. Manage credentials in the Yapily Console. See Authentication for details.

Headers

​
sub-application
string<uuid>

The sub-application ID to which event type is being subscribed to

Body

application/json;charset=UTF-8
​
institutionIdentifiers
object
required

Specifies the institution requirements for making the payment. Skips the bank selection screen in payment flow if the institutionId and institutionCountryCode are provided.

​
redirectUrl
string
required

URL of your server to redirect the user after completion of the payment flow.

Example:

"https://tpp-application.com"

​
paymentRequestDetails
object
required

Details of the payment.

​
userId
string<uuid>

Conditional. Yapily Identifier for the User returned by the create user step POST /users. You must provide either a userId or applicationUserId.

​
applicationUserId
string

Conditional. Your own User reference. This field allows you to use your own unique references for individual users. Where the User reference doesn't have an associated Yapily userId, a new userId is created and linked to it. You must provide either a userId or applicationUserId.

​
userSettings
object

Specifies the language and location preferences of the user.

Response

Created

​
meta
object
​
data
object