Create a Session

Create a Realtime Collections Session

curl --request POST \
  --url https://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Meridian-Api-Key: <x-meridian-api-key>' \
  --header 'X-Meridian-Signature: <api-key>' \
  --header 'X-Meridian-Timestamp: <x-meridian-timestamp>' \
  --data '
{
  "operatorId": "op-123",
  "operatorName": "Carlos Tester"
}
'

import requests

url = "https://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions"

payload = {
    "operatorId": "op-123",
    "operatorName": "Carlos Tester"
}
headers = {
    "X-Meridian-Api-Key": "<x-meridian-api-key>",
    "X-Meridian-Timestamp": "<x-meridian-timestamp>",
    "X-Meridian-Signature": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Meridian-Api-Key': '<x-meridian-api-key>',
    'X-Meridian-Timestamp': '<x-meridian-timestamp>',
    'X-Meridian-Signature': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({operatorId: 'op-123', operatorName: 'Carlos Tester'})
};

fetch('https://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions', 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://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions",
  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([
    'operatorId' => 'op-123',
    'operatorName' => 'Carlos Tester'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Meridian-Api-Key: <x-meridian-api-key>",
    "X-Meridian-Signature: <api-key>",
    "X-Meridian-Timestamp: <x-meridian-timestamp>"
  ],
]);

$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://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions"

	payload := strings.NewReader("{\n  \"operatorId\": \"op-123\",\n  \"operatorName\": \"Carlos Tester\"\n}")

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

	req.Header.Add("X-Meridian-Api-Key", "<x-meridian-api-key>")
	req.Header.Add("X-Meridian-Timestamp", "<x-meridian-timestamp>")
	req.Header.Add("X-Meridian-Signature", "<api-key>")
	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://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions")
  .header("X-Meridian-Api-Key", "<x-meridian-api-key>")
  .header("X-Meridian-Timestamp", "<x-meridian-timestamp>")
  .header("X-Meridian-Signature", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"operatorId\": \"op-123\",\n  \"operatorName\": \"Carlos Tester\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions")

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

request = Net::HTTP::Post.new(url)
request["X-Meridian-Api-Key"] = '<x-meridian-api-key>'
request["X-Meridian-Timestamp"] = '<x-meridian-timestamp>'
request["X-Meridian-Signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"operatorId\": \"op-123\",\n  \"operatorName\": \"Carlos Tester\"\n}"

response = http.request(request)
puts response.read_body

{
  "sessionKey": "uslocal-b1x2k0dzsbpc4cz8c8xrvfel",
  "expiresAt": "2026-07-02T20:45:50Z"
}

{
  "validationErrors": [
    {
      "type": "InvalidFormat",
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "errorCode": "<string>"
}

{
  "validationErrors": [
    {
      "type": "InvalidFormat",
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "errorCode": "<string>"
}

POST

payment-links

sessions

Create a Realtime Collections Session

curl --request POST \
  --url https://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Meridian-Api-Key: <x-meridian-api-key>' \
  --header 'X-Meridian-Signature: <api-key>' \
  --header 'X-Meridian-Timestamp: <x-meridian-timestamp>' \
  --data '
{
  "operatorId": "op-123",
  "operatorName": "Carlos Tester"
}
'

import requests

url = "https://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions"

payload = {
    "operatorId": "op-123",
    "operatorName": "Carlos Tester"
}
headers = {
    "X-Meridian-Api-Key": "<x-meridian-api-key>",
    "X-Meridian-Timestamp": "<x-meridian-timestamp>",
    "X-Meridian-Signature": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Meridian-Api-Key': '<x-meridian-api-key>',
    'X-Meridian-Timestamp': '<x-meridian-timestamp>',
    'X-Meridian-Signature': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({operatorId: 'op-123', operatorName: 'Carlos Tester'})
};

fetch('https://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions', 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://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions",
  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([
    'operatorId' => 'op-123',
    'operatorName' => 'Carlos Tester'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Meridian-Api-Key: <x-meridian-api-key>",
    "X-Meridian-Signature: <api-key>",
    "X-Meridian-Timestamp: <x-meridian-timestamp>"
  ],
]);

$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://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions"

	payload := strings.NewReader("{\n  \"operatorId\": \"op-123\",\n  \"operatorName\": \"Carlos Tester\"\n}")

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

	req.Header.Add("X-Meridian-Api-Key", "<x-meridian-api-key>")
	req.Header.Add("X-Meridian-Timestamp", "<x-meridian-timestamp>")
	req.Header.Add("X-Meridian-Signature", "<api-key>")
	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://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions")
  .header("X-Meridian-Api-Key", "<x-meridian-api-key>")
  .header("X-Meridian-Timestamp", "<x-meridian-timestamp>")
  .header("X-Meridian-Signature", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"operatorId\": \"op-123\",\n  \"operatorName\": \"Carlos Tester\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://us-merchant.sandbox.api-us.meridianapps.dev/v1/payment-links/sessions")

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

request = Net::HTTP::Post.new(url)
request["X-Meridian-Api-Key"] = '<x-meridian-api-key>'
request["X-Meridian-Timestamp"] = '<x-meridian-timestamp>'
request["X-Meridian-Signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"operatorId\": \"op-123\",\n  \"operatorName\": \"Carlos Tester\"\n}"

response = http.request(request)
puts response.read_body

{
  "sessionKey": "uslocal-b1x2k0dzsbpc4cz8c8xrvfel",
  "expiresAt": "2026-07-02T20:45:50Z"
}

{
  "validationErrors": [
    {
      "type": "InvalidFormat",
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "errorCode": "<string>"
}

{
  "validationErrors": [
    {
      "type": "InvalidFormat",
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ],
  "message": "<string>",
  "errorCode": "<string>"
}

Authorizations

X-Meridian-Signature

string

header

required

Meridian HMAC header authentication.

Required headers:

X-Meridian-Api-Key
X-Meridian-Timestamp
X-Meridian-Signature

X-Meridian-Signature is the HMAC SHA-256 signature of the canonical request string, computed per request as HMAC-SHA256(apiKey + timestamp + method + request URI including any query string + body). See Authentication for how to construct it.

Headers

X-Meridian-Api-Key

string

required

API key issued by Meridian during provisioning.

X-Meridian-Timestamp

string

required

Current time in milliseconds since the Unix epoch. Must be within 10 seconds of the request.

Body

application/json

Operator context used for auditing when creating a Realtime Collections API session.

operatorId

string

required

Unique identifier of the operator (user) initiating the session in the merchant system. Used for audit and traceability; must be present and non-blank but is not otherwise validated.

operatorName

string

required

Human-readable name of the operator (user) initiating the session, stored for audit logs so actions can be attributed to a specific person.

Response

Created the session and stored the contents for later use

Session key issued for the Realtime Collections API, valid for 15 minutes.

sessionKey

string

required

Unique session key to pass in the body of the create-payment-link request.

expiresAt

string<date-time>

required

ISO-8601 datetime (UTC) at which the session key expires, 15 minutes after it was issued.

Getting Started

API Reference

Authorizations

Headers

Body

Response