Skip to main content
POST
/
api
/
v1
/
payment-requests:redirect
Create a payment request via the redirect (Pay by Bank) flow
curl --request POST \
  --url https://core.quidkey.com/api/v1/payment-requests:redirect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchant_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone_number": "+447123456789"
  },
  "billing_address": {
    "address_line1": "12 West Common Drive",
    "address_line2": "Flat 1",
    "apartment": "Apt 5B",
    "city": "London",
    "state_province": "Greater London",
    "country": "GB",
    "postal_code": "SE1 1AA",
    "company_name": "Acme Ltd"
  },
  "amount": 1999,
  "currency": "GBP",
  "payment_reference": "ORDER123",
  "order_id": "1140",
  "locale": "en_GB",
  "success_url_redirect": "https://storename.com/success",
  "fail_url_redirect": "https://storename.com/failure",
  "test_transaction": false,
  "selected_bank_id": "38c39d03-8df3-4980-b0a8-7e283c8c62dd",
  "simulation": {
    "straddle": {
      "customer_outcome": "standard",
      "paykey_outcome": "standard",
      "charge_outcome": "standard",
      "balance_check": "required"
    },
    "flinks": {
      "outcome": "happy",
      "mfa": "skip"
    }
  }
}
'
import requests

url = "https://core.quidkey.com/api/v1/payment-requests:redirect"

payload = {
    "merchant_id": "550e8400-e29b-41d4-a716-446655440000",
    "customer": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone_number": "+447123456789"
    },
    "billing_address": {
        "address_line1": "12 West Common Drive",
        "address_line2": "Flat 1",
        "apartment": "Apt 5B",
        "city": "London",
        "state_province": "Greater London",
        "country": "GB",
        "postal_code": "SE1 1AA",
        "company_name": "Acme Ltd"
    },
    "amount": 1999,
    "currency": "GBP",
    "payment_reference": "ORDER123",
    "order_id": "1140",
    "locale": "en_GB",
    "success_url_redirect": "https://storename.com/success",
    "fail_url_redirect": "https://storename.com/failure",
    "test_transaction": False,
    "selected_bank_id": "38c39d03-8df3-4980-b0a8-7e283c8c62dd",
    "simulation": {
        "straddle": {
            "customer_outcome": "standard",
            "paykey_outcome": "standard",
            "charge_outcome": "standard",
            "balance_check": "required"
        },
        "flinks": {
            "outcome": "happy",
            "mfa": "skip"
        }
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    merchant_id: '550e8400-e29b-41d4-a716-446655440000',
    customer: {name: 'John Doe', email: 'john.doe@example.com', phone_number: '+447123456789'},
    billing_address: {
      address_line1: '12 West Common Drive',
      address_line2: 'Flat 1',
      apartment: 'Apt 5B',
      city: 'London',
      state_province: 'Greater London',
      country: 'GB',
      postal_code: 'SE1 1AA',
      company_name: 'Acme Ltd'
    },
    amount: 1999,
    currency: 'GBP',
    payment_reference: 'ORDER123',
    order_id: '1140',
    locale: 'en_GB',
    success_url_redirect: 'https://storename.com/success',
    fail_url_redirect: 'https://storename.com/failure',
    test_transaction: false,
    selected_bank_id: '38c39d03-8df3-4980-b0a8-7e283c8c62dd',
    simulation: {
      straddle: {
        customer_outcome: 'standard',
        paykey_outcome: 'standard',
        charge_outcome: 'standard',
        balance_check: 'required'
      },
      flinks: {outcome: 'happy', mfa: 'skip'}
    }
  })
};

fetch('https://core.quidkey.com/api/v1/payment-requests:redirect', 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://core.quidkey.com/api/v1/payment-requests:redirect",
  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([
    'merchant_id' => '550e8400-e29b-41d4-a716-446655440000',
    'customer' => [
        'name' => 'John Doe',
        'email' => 'john.doe@example.com',
        'phone_number' => '+447123456789'
    ],
    'billing_address' => [
        'address_line1' => '12 West Common Drive',
        'address_line2' => 'Flat 1',
        'apartment' => 'Apt 5B',
        'city' => 'London',
        'state_province' => 'Greater London',
        'country' => 'GB',
        'postal_code' => 'SE1 1AA',
        'company_name' => 'Acme Ltd'
    ],
    'amount' => 1999,
    'currency' => 'GBP',
    'payment_reference' => 'ORDER123',
    'order_id' => '1140',
    'locale' => 'en_GB',
    'success_url_redirect' => 'https://storename.com/success',
    'fail_url_redirect' => 'https://storename.com/failure',
    'test_transaction' => false,
    'selected_bank_id' => '38c39d03-8df3-4980-b0a8-7e283c8c62dd',
    'simulation' => [
        'straddle' => [
                'customer_outcome' => 'standard',
                'paykey_outcome' => 'standard',
                'charge_outcome' => 'standard',
                'balance_check' => 'required'
        ],
        'flinks' => [
                'outcome' => 'happy',
                'mfa' => 'skip'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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://core.quidkey.com/api/v1/payment-requests:redirect"

	payload := strings.NewReader("{\n  \"merchant_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"customer\": {\n    \"name\": \"John Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone_number\": \"+447123456789\"\n  },\n  \"billing_address\": {\n    \"address_line1\": \"12 West Common Drive\",\n    \"address_line2\": \"Flat 1\",\n    \"apartment\": \"Apt 5B\",\n    \"city\": \"London\",\n    \"state_province\": \"Greater London\",\n    \"country\": \"GB\",\n    \"postal_code\": \"SE1 1AA\",\n    \"company_name\": \"Acme Ltd\"\n  },\n  \"amount\": 1999,\n  \"currency\": \"GBP\",\n  \"payment_reference\": \"ORDER123\",\n  \"order_id\": \"1140\",\n  \"locale\": \"en_GB\",\n  \"success_url_redirect\": \"https://storename.com/success\",\n  \"fail_url_redirect\": \"https://storename.com/failure\",\n  \"test_transaction\": false,\n  \"selected_bank_id\": \"38c39d03-8df3-4980-b0a8-7e283c8c62dd\",\n  \"simulation\": {\n    \"straddle\": {\n      \"customer_outcome\": \"standard\",\n      \"paykey_outcome\": \"standard\",\n      \"charge_outcome\": \"standard\",\n      \"balance_check\": \"required\"\n    },\n    \"flinks\": {\n      \"outcome\": \"happy\",\n      \"mfa\": \"skip\"\n    }\n  }\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://core.quidkey.com/api/v1/payment-requests:redirect")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"customer\": {\n    \"name\": \"John Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone_number\": \"+447123456789\"\n  },\n  \"billing_address\": {\n    \"address_line1\": \"12 West Common Drive\",\n    \"address_line2\": \"Flat 1\",\n    \"apartment\": \"Apt 5B\",\n    \"city\": \"London\",\n    \"state_province\": \"Greater London\",\n    \"country\": \"GB\",\n    \"postal_code\": \"SE1 1AA\",\n    \"company_name\": \"Acme Ltd\"\n  },\n  \"amount\": 1999,\n  \"currency\": \"GBP\",\n  \"payment_reference\": \"ORDER123\",\n  \"order_id\": \"1140\",\n  \"locale\": \"en_GB\",\n  \"success_url_redirect\": \"https://storename.com/success\",\n  \"fail_url_redirect\": \"https://storename.com/failure\",\n  \"test_transaction\": false,\n  \"selected_bank_id\": \"38c39d03-8df3-4980-b0a8-7e283c8c62dd\",\n  \"simulation\": {\n    \"straddle\": {\n      \"customer_outcome\": \"standard\",\n      \"paykey_outcome\": \"standard\",\n      \"charge_outcome\": \"standard\",\n      \"balance_check\": \"required\"\n    },\n    \"flinks\": {\n      \"outcome\": \"happy\",\n      \"mfa\": \"skip\"\n    }\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://core.quidkey.com/api/v1/payment-requests:redirect")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchant_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"customer\": {\n    \"name\": \"John Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"phone_number\": \"+447123456789\"\n  },\n  \"billing_address\": {\n    \"address_line1\": \"12 West Common Drive\",\n    \"address_line2\": \"Flat 1\",\n    \"apartment\": \"Apt 5B\",\n    \"city\": \"London\",\n    \"state_province\": \"Greater London\",\n    \"country\": \"GB\",\n    \"postal_code\": \"SE1 1AA\",\n    \"company_name\": \"Acme Ltd\"\n  },\n  \"amount\": 1999,\n  \"currency\": \"GBP\",\n  \"payment_reference\": \"ORDER123\",\n  \"order_id\": \"1140\",\n  \"locale\": \"en_GB\",\n  \"success_url_redirect\": \"https://storename.com/success\",\n  \"fail_url_redirect\": \"https://storename.com/failure\",\n  \"test_transaction\": false,\n  \"selected_bank_id\": \"38c39d03-8df3-4980-b0a8-7e283c8c62dd\",\n  \"simulation\": {\n    \"straddle\": {\n      \"customer_outcome\": \"standard\",\n      \"paykey_outcome\": \"standard\",\n      \"charge_outcome\": \"standard\",\n      \"balance_check\": \"required\"\n    },\n    \"flinks\": {\n      \"outcome\": \"happy\",\n      \"mfa\": \"skip\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "success": true,
  "data": {
    "redirect_url": "https://example.com/redirect"
  }
}
{
  "success": false,
  "error": {
    "message": "Invalid input provided"
  }
}
{
  "success": false,
  "error": {
    "message": "Invalid input provided"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Strict input parameters for the redirect (Pay by Bank) payment request

Strict input parameters for the redirect (Pay by Bank) payment request

​
customer
Redirect Customer Input · object
required

Customer information for the redirect payment request

​
billing_address
Address · object
required

A physical address

​
amount
integer
required

Minor-unit amount (e.g. pence/cents). Decimals are rejected.

Required range: 1 <= x <= 9999999
Example:

1999

​
currency
string
required

The currency of the payment request

Required string length: 3
Pattern: ^[A-Za-z]{3}$
Examples:

"GBP"

"USD"

"EUR"

"JPY"

​
locale
string
required

The locale of the payment request

Example:

"en_GB"

​
merchant_id
string<uuid>

Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
payment_reference
string

Payment reference to appear on the payer’s bank statement (max 18 alphanumeric characters)

Maximum string length: 18
Pattern: ^[A-Za-z0-9]{1,18}$
Example:

"ORDER123"

​
order_id
string

The unique identifier for the merchant's order

Example:

"1140"

​
success_url_redirect
string

URL to redirect on successful payment

Example:

"https://storename.com/success"

​
fail_url_redirect
string

URL to redirect on failed payment

Example:

"https://storename.com/failure"

​
test_transaction
boolean

Flag for test transactions

Example:

false

​
selected_bank_id
string

Selected bank reference

Example:

"38c39d03-8df3-4980-b0a8-7e283c8c62dd"

​
simulation
object

Sandbox simulation config. Honoured only when the upstream provider is a fake/sandbox backend; live providers ignore it.

Response

Created

​
success
boolean
required

Indicates if the request was successful

Example:

true

​
data
Redirect Payment Request Data · object
required

Redirect payment request response data