Get payment status

curl --request GET \
  --url https://api.circle.com/v1/facilitator/x402/status/{paymentId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.circle.com/v1/facilitator/x402/status/{paymentId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.circle.com/v1/facilitator/x402/status/{paymentId}', 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.circle.com/v1/facilitator/x402/status/{paymentId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.circle.com/v1/facilitator/x402/status/{paymentId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.circle.com/v1/facilitator/x402/status/{paymentId}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "paymentId": "5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa",
  "status": "pending",
  "network": "eip155:5042002",
  "reason": "outcome_unknown",
  "transaction": "0x6f9e1d...",
  "amount": "1000000",
  "payer": null,
  "nextAction": null,
  "retryAfterMs": null,
  "expiresAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2026-06-11T22:30:11Z"
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

GET

facilitator

x402

status

{paymentId}

Get payment status

curl --request GET \
  --url https://api.circle.com/v1/facilitator/x402/status/{paymentId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.circle.com/v1/facilitator/x402/status/{paymentId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.circle.com/v1/facilitator/x402/status/{paymentId}', 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.circle.com/v1/facilitator/x402/status/{paymentId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.circle.com/v1/facilitator/x402/status/{paymentId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.circle.com/v1/facilitator/x402/status/{paymentId}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "paymentId": "5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa",
  "status": "pending",
  "network": "eip155:5042002",
  "reason": "outcome_unknown",
  "transaction": "0x6f9e1d...",
  "amount": "1000000",
  "payer": null,
  "nextAction": null,
  "retryAfterMs": null,
  "expiresAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2026-06-11T22:30:11Z"
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

{
  "code": 403,
  "message": "Registration required to continue settling on this address",
  "errors": [
    {
      "reason": "registration_required"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer token authentication with a Circle API key. Use this for production settlement after claiming your Facilitator Service seller account.

Path Parameters

paymentId

string<uuid>

required

The paymentId returned by /settle on a pending response.

Response

Payment status

paymentId

string<uuid>

required

Facilitator Service payment identifier.

Example:

"5b3f6c1e-9d2a-4f08-b1c7-2e9a14d0c3aa"

status

enum<string>

required

Current lifecycle state of the payment.

Available options:

pending,

completed,

failed

network

string

required

CAIP-2 network identifier for the payment.

Example:

"eip155:5042002"

reason

enum<string> | null

Additional detail about the payment status.

Available options:

outcome_unknown

Example:

"outcome_unknown"

transaction

string | null

Transaction hash once available.

Example:

"0x6f9e1d..."

amount

string

Amount in atomic USDC units.

Example:

"1000000"

payer

string | null

Buyer address on the settled transfer.

Example:

null

nextAction

string | null

The next action.

Example:

null

retryAfterMs

integer | null

Milliseconds before retry.

Example:

null

expiresAt

string<date-time> | null

Timestamp after which you can stop polling for a terminal state on this pending payment. Present only while status is pending.

updatedAt

string<date-time>

Timestamp of the most recent state transition.

Example:

"2026-06-11T22:30:11Z"