Create a session

cURL

curl --request POST \
  --url https://api.moonpay.com/platform/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "deviceIp": "0.0.0.0",
  "externalCustomerId": "user_01AN4Z07BY",
  "email": "user@example.com",
  "phoneNumber": "+14155551234",
  "termsAcceptedAt": "2026-05-28T14:21:00.000Z",
  "dateOfBirth": "1990-05-15T00:00:00.000Z"
}
'

import requests

url = "https://api.moonpay.com/platform/v1/sessions"

payload = {
    "deviceIp": "0.0.0.0",
    "externalCustomerId": "user_01AN4Z07BY",
    "email": "user@example.com",
    "phoneNumber": "+14155551234",
    "termsAcceptedAt": "2026-05-28T14:21:00.000Z",
    "dateOfBirth": "1990-05-15T00:00:00.000Z"
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    deviceIp: '0.0.0.0',
    externalCustomerId: 'user_01AN4Z07BY',
    email: 'user@example.com',
    phoneNumber: '+14155551234',
    termsAcceptedAt: '2026-05-28T14:21:00.000Z',
    dateOfBirth: '1990-05-15T00:00:00.000Z'
  })
};

fetch('https://api.moonpay.com/platform/v1/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://api.moonpay.com/platform/v1/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([
    'deviceIp' => '0.0.0.0',
    'externalCustomerId' => 'user_01AN4Z07BY',
    'email' => 'user@example.com',
    'phoneNumber' => '+14155551234',
    'termsAcceptedAt' => '2026-05-28T14:21:00.000Z',
    'dateOfBirth' => '1990-05-15T00:00:00.000Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$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.moonpay.com/platform/v1/sessions"

	payload := strings.NewReader("{\n  \"deviceIp\": \"0.0.0.0\",\n  \"externalCustomerId\": \"user_01AN4Z07BY\",\n  \"email\": \"user@example.com\",\n  \"phoneNumber\": \"+14155551234\",\n  \"termsAcceptedAt\": \"2026-05-28T14:21:00.000Z\",\n  \"dateOfBirth\": \"1990-05-15T00:00:00.000Z\"\n}")

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

	req.Header.Add("X-Api-Key", "<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://api.moonpay.com/platform/v1/sessions")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"deviceIp\": \"0.0.0.0\",\n  \"externalCustomerId\": \"user_01AN4Z07BY\",\n  \"email\": \"user@example.com\",\n  \"phoneNumber\": \"+14155551234\",\n  \"termsAcceptedAt\": \"2026-05-28T14:21:00.000Z\",\n  \"dateOfBirth\": \"1990-05-15T00:00:00.000Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.moonpay.com/platform/v1/sessions")

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

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deviceIp\": \"0.0.0.0\",\n  \"externalCustomerId\": \"user_01AN4Z07BY\",\n  \"email\": \"user@example.com\",\n  \"phoneNumber\": \"+14155551234\",\n  \"termsAcceptedAt\": \"2026-05-28T14:21:00.000Z\",\n  \"dateOfBirth\": \"1990-05-15T00:00:00.000Z\"\n}"

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

{
  "sessionToken": "c2Vzc2lvbi50b2tlbg"
}

{
  "code": "forbidden",
  "message": "Forbidden",
  "errors": [
    {
      "field": "source.amount",
      "message": "Source amount must be a numeric string. Example \"100\" or \"10.25\"."
    }
  ]
}

{
  "code": "service_unavailable",
  "message": "<string>"
}

POST

platform

sessions

cURL

curl --request POST \
  --url https://api.moonpay.com/platform/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "deviceIp": "0.0.0.0",
  "externalCustomerId": "user_01AN4Z07BY",
  "email": "user@example.com",
  "phoneNumber": "+14155551234",
  "termsAcceptedAt": "2026-05-28T14:21:00.000Z",
  "dateOfBirth": "1990-05-15T00:00:00.000Z"
}
'

import requests

url = "https://api.moonpay.com/platform/v1/sessions"

payload = {
    "deviceIp": "0.0.0.0",
    "externalCustomerId": "user_01AN4Z07BY",
    "email": "user@example.com",
    "phoneNumber": "+14155551234",
    "termsAcceptedAt": "2026-05-28T14:21:00.000Z",
    "dateOfBirth": "1990-05-15T00:00:00.000Z"
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    deviceIp: '0.0.0.0',
    externalCustomerId: 'user_01AN4Z07BY',
    email: 'user@example.com',
    phoneNumber: '+14155551234',
    termsAcceptedAt: '2026-05-28T14:21:00.000Z',
    dateOfBirth: '1990-05-15T00:00:00.000Z'
  })
};

fetch('https://api.moonpay.com/platform/v1/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://api.moonpay.com/platform/v1/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([
    'deviceIp' => '0.0.0.0',
    'externalCustomerId' => 'user_01AN4Z07BY',
    'email' => 'user@example.com',
    'phoneNumber' => '+14155551234',
    'termsAcceptedAt' => '2026-05-28T14:21:00.000Z',
    'dateOfBirth' => '1990-05-15T00:00:00.000Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$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.moonpay.com/platform/v1/sessions"

	payload := strings.NewReader("{\n  \"deviceIp\": \"0.0.0.0\",\n  \"externalCustomerId\": \"user_01AN4Z07BY\",\n  \"email\": \"user@example.com\",\n  \"phoneNumber\": \"+14155551234\",\n  \"termsAcceptedAt\": \"2026-05-28T14:21:00.000Z\",\n  \"dateOfBirth\": \"1990-05-15T00:00:00.000Z\"\n}")

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

	req.Header.Add("X-Api-Key", "<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://api.moonpay.com/platform/v1/sessions")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"deviceIp\": \"0.0.0.0\",\n  \"externalCustomerId\": \"user_01AN4Z07BY\",\n  \"email\": \"user@example.com\",\n  \"phoneNumber\": \"+14155551234\",\n  \"termsAcceptedAt\": \"2026-05-28T14:21:00.000Z\",\n  \"dateOfBirth\": \"1990-05-15T00:00:00.000Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.moonpay.com/platform/v1/sessions")

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

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deviceIp\": \"0.0.0.0\",\n  \"externalCustomerId\": \"user_01AN4Z07BY\",\n  \"email\": \"user@example.com\",\n  \"phoneNumber\": \"+14155551234\",\n  \"termsAcceptedAt\": \"2026-05-28T14:21:00.000Z\",\n  \"dateOfBirth\": \"1990-05-15T00:00:00.000Z\"\n}"

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

{
  "sessionToken": "c2Vzc2lvbi50b2tlbg"
}

{
  "code": "forbidden",
  "message": "Forbidden",
  "errors": [
    {
      "field": "source.amount",
      "message": "Source amount must be a numeric string. Example \"100\" or \"10.25\"."
    }
  ]
}

{
  "code": "service_unavailable",
  "message": "<string>"
}

Some Platform API capabilities must be enabled on your account by MoonPay before you can call them. If this endpoint returns an unexpected 404, see Capability enablement.

Authorizations

X-Api-Key

string

header

required

Secret key authentication via the X-Api-Key header.

Example: X-Api-Key: <secretKey>

Body

application/json

deviceIp

required

The IP address of the user's device to ensure the integrity of the session. Both IPv4 and IPv6 values are supported.

Example:

"0.0.0.0"

externalCustomerId

string

A unique identifier for the customer from your system.

Required string length: 1 - 255

Example:

"user_01AN4Z07BY"

string<email>

The customer's email address. Must be a valid email. If provided, enables email OTP authentication.

Required string length: 5 - 255

Example:

"user@example.com"

phoneNumber

string

The customer's phone number in E.164 format. If both email and phone are provided, enables phone OTP authentication for returning customers. Send only a number you have verified belongs to the customer: when a signed-in customer with no verified phone number authorizes, MoonPay saves it as their verified phone number and the phoneNumber KYC requirement is cleared. If it can't be saved (for example, it is already verified for another customer), authorization still succeeds and phoneNumber stays outstanding.

Pattern: ^\+[1-9]\d{1,14}$

Example:

"+14155551234"

termsAcceptedAt

string<utc-date-time>

An ISO 8601 timestamp of when the customer accepted MoonPay's Terms of Use. Send this when you capture Terms of Use acceptance in your own UI. The value can be at most 60 seconds ahead of server time, with no past limit. MoonPay records the terms version live at this timestamp and binds the acceptance to the customer when the session is authorized. Only send this field if you use the Customer API or Guest Checkout; otherwise the request fails with a 503 service_unavailable error.

Example:

"2026-05-28T14:21:00.000Z"

dateOfBirth

string<utc-date-time>

Customer's date of birth as an ISO 8601 timestamp. Optional. Send this for Guest Checkout when the customer is in the EEA so it can be stored on the customer record after authorize. Must represent an age between 18 and 100 years. Omitting it does not block session creation.

Example:

"1990-05-15T00:00:00.000Z"

Response

The request has succeeded.

sessionToken

string

required

An opaque session token used to set up a connection on your frontend. This token is single-use and must be generated each time the customer visits your app.

Token expires 24 hours after issuance.

Required string length: 1 - 8192

Example:

"c2Vzc2lvbi50b2tlbg"

Documentation

Sessions

Customers

Payment Methods

Assets

Quotes

Transactions

Webhooks

Objects & Types

Authorizations

Body

Response