curl --request POST \
--url https://api.natural.com/card-sessions/{sessionId}/claim \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.natural.com/card-sessions/{sessionId}/claim"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.natural.com/card-sessions/{sessionId}/claim', 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.natural.com/card-sessions/{sessionId}/claim",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
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.natural.com/card-sessions/{sessionId}/claim"
req, _ := http.NewRequest("POST", 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))
}HttpResponse<String> response = Unirest.post("https://api.natural.com/card-sessions/{sessionId}/claim")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.natural.com/card-sessions/{sessionId}/claim")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"sessionId": "csn_01a0e6466ba3713bba0f0d9d36803b92",
"cardId": "eac_01a0e642ed4873d685273ce0e7d1ccab",
"card": {
"number": "4242423289715897",
"cvc": "128",
"expirationMonth": 8,
"expirationYear": 2030,
"holderName": "Jane Appleseed"
},
"billingAddress": {
"line1": "235 2nd Street",
"line2": null,
"city": "San Francisco",
"state": "CA",
"postalCode": "94105",
"country": "US"
},
"proxy": {
"host": "us-va.browser.relay.evervault.app",
"port": 443,
"protocol": "https",
"username": "app_1a2b3c4d5e6f",
"password": "eyJhbGciOiJ...redacted",
"caBundleUrl": "https://ca.evervault.com"
},
"allowedHosts": [
"api.stripe.com"
],
"expiresAt": "2026-09-29T18:12:00.000Z",
"instructions": [
"Use the stand-in card through the proxy. The returned card fields resolve to the saved card only when sent to allowedHosts through the returned proxy before expiresAt.",
"Use the returned connection settings. Configure the proxy using protocol, host, port, username, and password. Keep the claim credentials secret; never include them in logs.",
"Trust the proxy certificate. Add the CA from caBundleUrl to the trust configuration used by your browser or HTTP client, preserving its existing trusted certificates. Keep TLS verification enabled.",
"Route the payment requests. Ensure requests to allowedHosts from the checkout page and its frames pass through the proxy. Configure routing before submitting payment.",
"Keep interception active. If you intercept requests, keep the runtime's event loop running so handlers can receive and forward them. Avoid blocking waits that prevent handlers from executing.",
"Verify routing before paying. Use a harmless request to an allowed host to confirm that the browser's traffic actually passes through the proxy.",
"Stop on routing failures. Do not forward card requests directly when the proxy fails. Check routing, certificate trust, and credential expiry before retrying payment, and first confirm the previous attempt did not complete."
]
}{
"errors": [
{
"code": "invalid_value",
"detail": "The information you entered isn't valid. Please check it and try again.",
"status": "400",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "unauthenticated",
"detail": "Authentication is required.",
"status": "401",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "forbidden",
"detail": "You do not have permission to perform this action.",
"status": "403",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_found",
"detail": "The requested resource was not found.",
"status": "404",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "conflict",
"detail": "The request conflicts with the current resource state.",
"status": "409",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "invalid_value",
"detail": "Too big: expected string to have <=80 characters",
"status": "422",
"source": {
"pointer": "/data/attributes/description"
},
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "mfa_required",
"detail": "MFA verification required",
"status": "428",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "rate_limited",
"detail": "Too many requests. Please try again later.",
"status": "429",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "server_error",
"detail": "Something went wrong.",
"status": "500",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_implemented",
"detail": "This operation is not available.",
"status": "501",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "bad_gateway",
"detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.",
"status": "502",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "service_unavailable",
"detail": "The service is temporarily unavailable.",
"status": "503",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}Claim card session
Claim the stand-in card and proxy login for an approved session. It succeeds once, and the credential can’t be fetched again.
curl --request POST \
--url https://api.natural.com/card-sessions/{sessionId}/claim \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.natural.com/card-sessions/{sessionId}/claim"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.natural.com/card-sessions/{sessionId}/claim', 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.natural.com/card-sessions/{sessionId}/claim",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
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.natural.com/card-sessions/{sessionId}/claim"
req, _ := http.NewRequest("POST", 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))
}HttpResponse<String> response = Unirest.post("https://api.natural.com/card-sessions/{sessionId}/claim")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.natural.com/card-sessions/{sessionId}/claim")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"sessionId": "csn_01a0e6466ba3713bba0f0d9d36803b92",
"cardId": "eac_01a0e642ed4873d685273ce0e7d1ccab",
"card": {
"number": "4242423289715897",
"cvc": "128",
"expirationMonth": 8,
"expirationYear": 2030,
"holderName": "Jane Appleseed"
},
"billingAddress": {
"line1": "235 2nd Street",
"line2": null,
"city": "San Francisco",
"state": "CA",
"postalCode": "94105",
"country": "US"
},
"proxy": {
"host": "us-va.browser.relay.evervault.app",
"port": 443,
"protocol": "https",
"username": "app_1a2b3c4d5e6f",
"password": "eyJhbGciOiJ...redacted",
"caBundleUrl": "https://ca.evervault.com"
},
"allowedHosts": [
"api.stripe.com"
],
"expiresAt": "2026-09-29T18:12:00.000Z",
"instructions": [
"Use the stand-in card through the proxy. The returned card fields resolve to the saved card only when sent to allowedHosts through the returned proxy before expiresAt.",
"Use the returned connection settings. Configure the proxy using protocol, host, port, username, and password. Keep the claim credentials secret; never include them in logs.",
"Trust the proxy certificate. Add the CA from caBundleUrl to the trust configuration used by your browser or HTTP client, preserving its existing trusted certificates. Keep TLS verification enabled.",
"Route the payment requests. Ensure requests to allowedHosts from the checkout page and its frames pass through the proxy. Configure routing before submitting payment.",
"Keep interception active. If you intercept requests, keep the runtime's event loop running so handlers can receive and forward them. Avoid blocking waits that prevent handlers from executing.",
"Verify routing before paying. Use a harmless request to an allowed host to confirm that the browser's traffic actually passes through the proxy.",
"Stop on routing failures. Do not forward card requests directly when the proxy fails. Check routing, certificate trust, and credential expiry before retrying payment, and first confirm the previous attempt did not complete."
]
}{
"errors": [
{
"code": "invalid_value",
"detail": "The information you entered isn't valid. Please check it and try again.",
"status": "400",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "unauthenticated",
"detail": "Authentication is required.",
"status": "401",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "forbidden",
"detail": "You do not have permission to perform this action.",
"status": "403",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_found",
"detail": "The requested resource was not found.",
"status": "404",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "conflict",
"detail": "The request conflicts with the current resource state.",
"status": "409",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "invalid_value",
"detail": "Too big: expected string to have <=80 characters",
"status": "422",
"source": {
"pointer": "/data/attributes/description"
},
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "mfa_required",
"detail": "MFA verification required",
"status": "428",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "rate_limited",
"detail": "Too many requests. Please try again later.",
"status": "429",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "server_error",
"detail": "Something went wrong.",
"status": "500",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_implemented",
"detail": "This operation is not available.",
"status": "501",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "bad_gateway",
"detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.",
"status": "502",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "service_unavailable",
"detail": "The service is temporarily unavailable.",
"status": "503",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}Authorizations
Bearer authentication: send your API key, agent key, or OAuth access token as Authorization: Bearer <credential>.
Headers
Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money.
1024Path Parameters
^csn_[0-9a-f]{32}$Query Parameters
Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.
^pty_[0-9a-f]{32}$Response
Successful Response
Show child attributes
Show child attributes
The card's billing address on file, for filling the merchant's checkout (the ZIP drives the bank's AVS check). Null for Natural-issued cards, which store none.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
64Instructions for configuring and verifying the checkout proxy before paying.
Was this page helpful?