Skip to main content
Create Hosted Commercial VRP request
curl --request POST \
  --url https://api.yapily.com/hosted/vrp-requests/commercial \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "00000000-0000-0000-0000-000000000000",
  "applicationUserId": "any",
  "userSettings": {
    "language": "EN",
    "location": "GB"
  },
  "institutionIdentifiers": {
    "institutionId": "mock-sandbox",
    "institutionCountryCode": "GB"
  },
  "controlParameters": {
    "maxAmountPerPayment": {
      "amount": 1.23,
      "currency": "GBP"
    },
    "periodicLimit": {
      "frequency": "MONTHLY",
      "maxAmount": {
        "amount": 2.46,
        "currency": "GBP"
      }
    },
    "validFrom": "2026-01-01T00:00:00Z",
    "validTo": "2027-02-02T11:59:59Z"
  },
  "initiationDetails": {
    "reference": "Test",
    "payee": {
      "name": "Mr. Beneficiary",
      "accountIdentifications": [
        {
          "type": "SORT_CODE",
          "identification": "112233"
        },
        {
          "type": "ACCOUNT_NUMBER",
          "identification": "12345678"
        }
      ]
    }
  },
  "redirectUrl": "https://parameter-viewer.yapily.com/",
  "oneTimeToken": true,
  "riskDetails": {
    "paymentContextCode": "TransferToThirdParty",
    "paymentPurposeCode": "OTHR",
    "categoryPurposeCode": "OTHR",
    "merchantCustomerId": "00000000-0000-0000-0000-000000000000",
    "isPayeePrepopulated": false,
    "payeeAccountType": "Personal"
  }
}
'
import requests

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

payload = {
    "userId": "00000000-0000-0000-0000-000000000000",
    "applicationUserId": "any",
    "userSettings": {
        "language": "EN",
        "location": "GB"
    },
    "institutionIdentifiers": {
        "institutionId": "mock-sandbox",
        "institutionCountryCode": "GB"
    },
    "controlParameters": {
        "maxAmountPerPayment": {
            "amount": 1.23,
            "currency": "GBP"
        },
        "periodicLimit": {
            "frequency": "MONTHLY",
            "maxAmount": {
                "amount": 2.46,
                "currency": "GBP"
            }
        },
        "validFrom": "2026-01-01T00:00:00Z",
        "validTo": "2027-02-02T11:59:59Z"
    },
    "initiationDetails": {
        "reference": "Test",
        "payee": {
            "name": "Mr. Beneficiary",
            "accountIdentifications": [
                {
                    "type": "SORT_CODE",
                    "identification": "112233"
                },
                {
                    "type": "ACCOUNT_NUMBER",
                    "identification": "12345678"
                }
            ]
        }
    },
    "redirectUrl": "https://parameter-viewer.yapily.com/",
    "oneTimeToken": True,
    "riskDetails": {
        "paymentContextCode": "TransferToThirdParty",
        "paymentPurposeCode": "OTHR",
        "categoryPurposeCode": "OTHR",
        "merchantCustomerId": "00000000-0000-0000-0000-000000000000",
        "isPayeePrepopulated": False,
        "payeeAccountType": "Personal"
    }
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    userId: '00000000-0000-0000-0000-000000000000',
    applicationUserId: 'any',
    userSettings: {language: 'EN', location: 'GB'},
    institutionIdentifiers: {institutionId: 'mock-sandbox', institutionCountryCode: 'GB'},
    controlParameters: {
      maxAmountPerPayment: {amount: 1.23, currency: 'GBP'},
      periodicLimit: {frequency: 'MONTHLY', maxAmount: {amount: 2.46, currency: 'GBP'}},
      validFrom: '2026-01-01T00:00:00Z',
      validTo: '2027-02-02T11:59:59Z'
    },
    initiationDetails: {
      reference: 'Test',
      payee: {
        name: 'Mr. Beneficiary',
        accountIdentifications: [
          {type: 'SORT_CODE', identification: '112233'},
          {type: 'ACCOUNT_NUMBER', identification: '12345678'}
        ]
      }
    },
    redirectUrl: 'https://parameter-viewer.yapily.com/',
    oneTimeToken: true,
    riskDetails: {
      paymentContextCode: 'TransferToThirdParty',
      paymentPurposeCode: 'OTHR',
      categoryPurposeCode: 'OTHR',
      merchantCustomerId: '00000000-0000-0000-0000-000000000000',
      isPayeePrepopulated: false,
      payeeAccountType: 'Personal'
    }
  })
};

fetch('https://api.yapily.com/hosted/vrp-requests/commercial', 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/vrp-requests/commercial",
  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' => '00000000-0000-0000-0000-000000000000',
    'applicationUserId' => 'any',
    'userSettings' => [
        'language' => 'EN',
        'location' => 'GB'
    ],
    'institutionIdentifiers' => [
        'institutionId' => 'mock-sandbox',
        'institutionCountryCode' => 'GB'
    ],
    'controlParameters' => [
        'maxAmountPerPayment' => [
                'amount' => 1.23,
                'currency' => 'GBP'
        ],
        'periodicLimit' => [
                'frequency' => 'MONTHLY',
                'maxAmount' => [
                                'amount' => 2.46,
                                'currency' => 'GBP'
                ]
        ],
        'validFrom' => '2026-01-01T00:00:00Z',
        'validTo' => '2027-02-02T11:59:59Z'
    ],
    'initiationDetails' => [
        'reference' => 'Test',
        'payee' => [
                'name' => 'Mr. Beneficiary',
                'accountIdentifications' => [
                                [
                                                                'type' => 'SORT_CODE',
                                                                'identification' => '112233'
                                ],
                                [
                                                                'type' => 'ACCOUNT_NUMBER',
                                                                'identification' => '12345678'
                                ]
                ]
        ]
    ],
    'redirectUrl' => 'https://parameter-viewer.yapily.com/',
    'oneTimeToken' => true,
    'riskDetails' => [
        'paymentContextCode' => 'TransferToThirdParty',
        'paymentPurposeCode' => 'OTHR',
        'categoryPurposeCode' => 'OTHR',
        'merchantCustomerId' => '00000000-0000-0000-0000-000000000000',
        'isPayeePrepopulated' => false,
        'payeeAccountType' => 'Personal'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$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/vrp-requests/commercial"

	payload := strings.NewReader("{\n  \"userId\": \"00000000-0000-0000-0000-000000000000\",\n  \"applicationUserId\": \"any\",\n  \"userSettings\": {\n    \"language\": \"EN\",\n    \"location\": \"GB\"\n  },\n  \"institutionIdentifiers\": {\n    \"institutionId\": \"mock-sandbox\",\n    \"institutionCountryCode\": \"GB\"\n  },\n  \"controlParameters\": {\n    \"maxAmountPerPayment\": {\n      \"amount\": 1.23,\n      \"currency\": \"GBP\"\n    },\n    \"periodicLimit\": {\n      \"frequency\": \"MONTHLY\",\n      \"maxAmount\": {\n        \"amount\": 2.46,\n        \"currency\": \"GBP\"\n      }\n    },\n    \"validFrom\": \"2026-01-01T00:00:00Z\",\n    \"validTo\": \"2027-02-02T11:59:59Z\"\n  },\n  \"initiationDetails\": {\n    \"reference\": \"Test\",\n    \"payee\": {\n      \"name\": \"Mr. Beneficiary\",\n      \"accountIdentifications\": [\n        {\n          \"type\": \"SORT_CODE\",\n          \"identification\": \"112233\"\n        },\n        {\n          \"type\": \"ACCOUNT_NUMBER\",\n          \"identification\": \"12345678\"\n        }\n      ]\n    }\n  },\n  \"redirectUrl\": \"https://parameter-viewer.yapily.com/\",\n  \"oneTimeToken\": true,\n  \"riskDetails\": {\n    \"paymentContextCode\": \"TransferToThirdParty\",\n    \"paymentPurposeCode\": \"OTHR\",\n    \"categoryPurposeCode\": \"OTHR\",\n    \"merchantCustomerId\": \"00000000-0000-0000-0000-000000000000\",\n    \"isPayeePrepopulated\": false,\n    \"payeeAccountType\": \"Personal\"\n  }\n}")

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

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

	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/vrp-requests/commercial")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"00000000-0000-0000-0000-000000000000\",\n  \"applicationUserId\": \"any\",\n  \"userSettings\": {\n    \"language\": \"EN\",\n    \"location\": \"GB\"\n  },\n  \"institutionIdentifiers\": {\n    \"institutionId\": \"mock-sandbox\",\n    \"institutionCountryCode\": \"GB\"\n  },\n  \"controlParameters\": {\n    \"maxAmountPerPayment\": {\n      \"amount\": 1.23,\n      \"currency\": \"GBP\"\n    },\n    \"periodicLimit\": {\n      \"frequency\": \"MONTHLY\",\n      \"maxAmount\": {\n        \"amount\": 2.46,\n        \"currency\": \"GBP\"\n      }\n    },\n    \"validFrom\": \"2026-01-01T00:00:00Z\",\n    \"validTo\": \"2027-02-02T11:59:59Z\"\n  },\n  \"initiationDetails\": {\n    \"reference\": \"Test\",\n    \"payee\": {\n      \"name\": \"Mr. Beneficiary\",\n      \"accountIdentifications\": [\n        {\n          \"type\": \"SORT_CODE\",\n          \"identification\": \"112233\"\n        },\n        {\n          \"type\": \"ACCOUNT_NUMBER\",\n          \"identification\": \"12345678\"\n        }\n      ]\n    }\n  },\n  \"redirectUrl\": \"https://parameter-viewer.yapily.com/\",\n  \"oneTimeToken\": true,\n  \"riskDetails\": {\n    \"paymentContextCode\": \"TransferToThirdParty\",\n    \"paymentPurposeCode\": \"OTHR\",\n    \"categoryPurposeCode\": \"OTHR\",\n    \"merchantCustomerId\": \"00000000-0000-0000-0000-000000000000\",\n    \"isPayeePrepopulated\": false,\n    \"payeeAccountType\": \"Personal\"\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

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

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'
request.body = "{\n  \"userId\": \"00000000-0000-0000-0000-000000000000\",\n  \"applicationUserId\": \"any\",\n  \"userSettings\": {\n    \"language\": \"EN\",\n    \"location\": \"GB\"\n  },\n  \"institutionIdentifiers\": {\n    \"institutionId\": \"mock-sandbox\",\n    \"institutionCountryCode\": \"GB\"\n  },\n  \"controlParameters\": {\n    \"maxAmountPerPayment\": {\n      \"amount\": 1.23,\n      \"currency\": \"GBP\"\n    },\n    \"periodicLimit\": {\n      \"frequency\": \"MONTHLY\",\n      \"maxAmount\": {\n        \"amount\": 2.46,\n        \"currency\": \"GBP\"\n      }\n    },\n    \"validFrom\": \"2026-01-01T00:00:00Z\",\n    \"validTo\": \"2027-02-02T11:59:59Z\"\n  },\n  \"initiationDetails\": {\n    \"reference\": \"Test\",\n    \"payee\": {\n      \"name\": \"Mr. Beneficiary\",\n      \"accountIdentifications\": [\n        {\n          \"type\": \"SORT_CODE\",\n          \"identification\": \"112233\"\n        },\n        {\n          \"type\": \"ACCOUNT_NUMBER\",\n          \"identification\": \"12345678\"\n        }\n      ]\n    }\n  },\n  \"redirectUrl\": \"https://parameter-viewer.yapily.com/\",\n  \"oneTimeToken\": true,\n  \"riskDetails\": {\n    \"paymentContextCode\": \"TransferToThirdParty\",\n    \"paymentPurposeCode\": \"OTHR\",\n    \"categoryPurposeCode\": \"OTHR\",\n    \"merchantCustomerId\": \"00000000-0000-0000-0000-000000000000\",\n    \"isPayeePrepopulated\": false,\n    \"payeeAccountType\": \"Personal\"\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "meta": {
    "tracingId": "12345678901234567890123456789012"
  },
  "data": {
    "requestId": "00000000-0000-0000-0000-000000000000",
    "institutionIdentifiers": {
      "institutionId": "mock-sandbox",
      "institutionCountryCode": "GB"
    },
    "userSettings": {
      "language": "EN",
      "location": "GB"
    },
    "hostedUrl": "https://...",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "authorisationExpiresAt": "2027-02-02T11:59:59.000Z"
  }
}
{
  "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"
      }
    ]
  }
}

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.

Body

application/json
​
applicationUserId
string
required
​
institutionIdentifiers
object
required
​
controlParameters
object
required

Mandatory. The parameters for the VRP mandate.

​
redirectUrl
string
required

Mandatory. The URL to redirect to once the Hosted VRP flow finishes.

​
riskDetails
object
required

Mandatory. The details required by the institutions to detect and prevent fraud.

​
userId
string<uuid>
​
userSettings
object
​
initiationDetails
object

Optional. The details of the participating parties.

​
oneTimeToken
boolean

Optional. Set to true in order for the redirect to return the consent token secured with a one-time token (instead of a plain consent token).

Response

OK

​
meta
object
required
​
data
object
required