Authentication
The Xtrm API uses bearer tokens. Exchange your API credentials (client_id and client_secret) for an access_token, then send that token in the Authorization header of every other request, including the calls that create a batch payment and check its status. The token expires 24 hours after it's issued. Then get a new one with your refresh_token or your credentials.
- Get your API credentials
In your sandbox company account, go to Settings > Integrations > Get Credentials to get your
client_idandclient_secret. See Get your API credentials. - Request an access token
Send the credentials, form-encoded, to
/oAuth/tokenwithgrant_type=password. See Request an access token. - Send the token with every request
Add
Authorization: Bearer <access_token>to every other call, including every batch payment call. See Send the token with every request. - Get a new token when it expires
Each token expires 24 hours after it's issued. Call
/oAuth/tokenagain withgrant_type=refresh_tokenand yourrefresh_token, which lasts 60 days, or withgrant_type=password. See Renew a token.
#Get your API credentials
To get sandbox credentials, log in to your sandbox company account at https://sandbox.xtrm.com and go to Settings > Integrations > Get Credentials. On the same screen, request the IP addresses you will call the API from. Xtrm approves them and then adds test funds to your sandbox wallets. See Sandbox & environments for the full signup flow.
After you finish testing in the sandbox, Xtrm holds a call with you to confirm that you're ready for production. In production, you get your credentials the same way, under Settings > Integrations > Get Credentials in your live company account at https://www.xtrm.com, and request your production IP addresses there for Xtrm to approve.
Keep your client secret on your server
The token request doesn't take a bearer token: your API credentials, sent over HTTPS, are what authenticate it, so treat client_secret like a password. Load your credentials from environment variables or a secrets manager, never put them in browser or mobile app code, and never commit them to source control. Every sample on this page reads them from XTRM_CLIENT_ID and XTRM_CLIENT_SECRET.
#Which account a token acts for
Your API credentials belong to your company, the SPN account that owns them. The token response echoes the client_id it was issued to, and most requests name your company again in IssuerAccountNumber: the SPN of the company tied to the credentials you use. If you run payments for client companies as a managing platform, you use each company's pseudo credentials instead, and IssuerAccountNumber is that company's SPN. Pseudo credentials require manager services: Xtrm has to turn manager services on for your company before you can get or use a client company's pseudo credentials. See Pseudo credentials.
Xtrm checks that your bearer token can act for the account in IssuerAccountNumber. If it can't, the request fails with 401; on a batch payment, with Key Unauthorized. The two batch status calls take no IssuerAccountNumber: Xtrm checks your token against the account that submitted the batch, and a batch your token can't access returns 401.
#Request an access token
Send a POST to https://xapisandbox.xtrm.com/oAuth/token. The token endpoint sits at the host root, not under the /API/v4 base path that every other endpoint uses, and it is the only endpoint that takes a form-encoded body. On the wire, a request looks like this:
POST /oAuth/token HTTP/1.1
Host: xapisandbox.xtrm.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
grant_type=password&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRETIn production, send the same request to https://xapi.xtrm.com/oAuth/token.
Send these form fields:
| Field | Required | Description |
|---|---|---|
grant_type | Yes | password to get a token with your credentials, or refresh_token to get one with a refresh token. While your current token is valid, both return that same token. |
client_id | Yes | Your Xtrm-supplied client ID. Required for both grant types. |
client_secret | Yes | Your Xtrm-supplied client secret. Required for both grant types. |
refresh_token | Only to renew | The refresh_token from a previous successful token response. Send it only when grant_type is refresh_token. |
To start a session, set grant_type to password:
curl -X POST "https://xapisandbox.xtrm.com/oAuth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
--data-urlencode "grant_type=password" \
--data-urlencode "client_id=$XTRM_CLIENT_ID" \
--data-urlencode "client_secret=$XTRM_CLIENT_SECRET"const response = await fetch('https://xapisandbox.xtrm.com/oAuth/token', {
method: 'POST',
headers: {
Accept: 'application/json',
},
body: new URLSearchParams({
grant_type: 'password',
client_id: process.env.XTRM_CLIENT_ID,
client_secret: process.env.XTRM_CLIENT_SECRET,
}),
});
const token = await response.json();
console.log(JSON.stringify(token, null, 2));import os
import requests
response = requests.post(
"https://xapisandbox.xtrm.com/oAuth/token",
headers={"Accept": "application/json"},
data={
"grant_type": "password",
"client_id": os.environ["XTRM_CLIENT_ID"],
"client_secret": os.environ["XTRM_CLIENT_SECRET"],
},
)
response.raise_for_status()
print(response.json())using System.Net.Http.Headers;
using var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
["grant_type"] = "password",
["client_id"] = Environment.GetEnvironmentVariable("XTRM_CLIENT_ID")!,
["client_secret"] = Environment.GetEnvironmentVariable("XTRM_CLIENT_SECRET")!,
});
var response = await client.PostAsync("https://xapisandbox.xtrm.com/oAuth/token", form);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
String form = "grant_type=password"
+ "&client_id=" + URLEncoder.encode(System.getenv("XTRM_CLIENT_ID"), StandardCharsets.UTF_8)
+ "&client_secret=" + URLEncoder.encode(System.getenv("XTRM_CLIENT_SECRET"), StandardCharsets.UTF_8);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/oAuth/token"))
.header("Content-Type", "application/x-www-form-urlencoded")
.header("Accept", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());<?php
$ch = curl_init('https://xapisandbox.xtrm.com/oAuth/token');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'grant_type' => 'password',
'client_id' => getenv('XTRM_CLIENT_ID'),
'client_secret' => getenv('XTRM_CLIENT_SECRET'),
]),
CURLOPT_HTTPHEADER => [
'Content-Type: application/x-www-form-urlencoded',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));The samples print the whole response so you can copy the token while you test. In your application, keep tokens out of logs.
#The token response
A successful request returns HTTP 200 with a flat JSON object. Unlike most endpoints, the token response has no <Name>Response wrapper and no OperationStatus (see Requests & responses).
{
"access_token": "YOUR_ACCESS_TOKEN",
"token_type": "bearer",
"expires_in": 86399,
"refresh_token": "YOUR_REFRESH_TOKEN",
".issued": "Tue, 27 Oct 2026 14:58:21 GMT",
".expires": "Wed, 28 Oct 2026 14:58:21 GMT",
"client_id": "YOUR_CLIENT_ID"
}| Field | Type | Description |
|---|---|---|
access_token | string | The bearer token to send with your other API calls. |
token_type | string | The token type: bearer. |
expires_in | integer | Seconds until the access_token expires, 86399 (about 24 hours) in the example. |
refresh_token | string | Send it with grant_type=refresh_token to renew the session. It expires 60 days after it's issued. |
.issued | string | When the token was issued, as a date string such as Tue, 27 Oct 2026 14:58:21 GMT. |
.expires | string | When the token expires, as a date string such as Wed, 28 Oct 2026 14:58:21 GMT. |
client_id | string | The client ID the token was issued to. |
Tip
.issued and .expires start with a dot, so most languages need bracket or key access to read them, for example token['.expires'] in JavaScript.
#Token lifetime and expiry
These rules govern how long a token lasts:
- The
access_tokenexpires at a fixed time, 24 hours after it's issued. Using it doesn't extend it, however busy your integration is. - While your current token is valid, a token request with either grant returns that same token with its original
.issuedand.expires, soexpires_inis the time left. A new token is issued only after the current one expires. - The
refresh_tokenexpires 60 days after it's issued. Every token response returns your currentrefresh_token, so keep the one from your most recent response. - Once your
refresh_tokenhas expired, or if arefresh_tokengrant returns400withinvalid_grant, get a new token withgrant_type=password. That response carries arefresh_tokenfor the next 60 days.
The response tells you when the token expires: in the example, expires_in is 86399 seconds and .expires is 24 hours after .issued. Once that time has passed, every endpoint rejects the token with 401 and invalid_token (The Token has expired). If a new token has already been issued for the same credentials (for example by another process), the old token is no longer recognized and gets 401 invalid_authorization instead. Fetch the current token before you suspect your IP allowlist. We recommend checking .expires before you send a request and getting a new token once it has passed.
Long-running integrations need a new token
A token expires 24 hours after it's issued, even if you call the API constantly, and you can't renew it early: until it expires, a token request returns the same token with the same .expires. If your integration runs for longer than that, or runs a job once a day or less, check .expires before each batch and during long jobs, and get a new token once it has passed, with a refresh_token or a password grant.
#Renew a token
To renew a session, call /oAuth/token again with grant_type set to refresh_token. Send your client_id and client_secret as well, plus the refresh_token from your most recent token response. Replace YOUR_REFRESH_TOKEN in the samples with that value.
curl -X POST "https://xapisandbox.xtrm.com/oAuth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "client_id=$XTRM_CLIENT_ID" \
--data-urlencode "client_secret=$XTRM_CLIENT_SECRET" \
--data-urlencode "refresh_token=YOUR_REFRESH_TOKEN"const response = await fetch('https://xapisandbox.xtrm.com/oAuth/token', {
method: 'POST',
headers: {
Accept: 'application/json',
},
body: new URLSearchParams({
grant_type: 'refresh_token',
client_id: process.env.XTRM_CLIENT_ID,
client_secret: process.env.XTRM_CLIENT_SECRET,
refresh_token: 'YOUR_REFRESH_TOKEN',
}),
});
const token = await response.json();
console.log(JSON.stringify(token, null, 2));import os
import requests
response = requests.post(
"https://xapisandbox.xtrm.com/oAuth/token",
headers={"Accept": "application/json"},
data={
"grant_type": "refresh_token",
"client_id": os.environ["XTRM_CLIENT_ID"],
"client_secret": os.environ["XTRM_CLIENT_SECRET"],
"refresh_token": "YOUR_REFRESH_TOKEN",
},
)
response.raise_for_status()
print(response.json())using System.Net.Http.Headers;
using var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
["grant_type"] = "refresh_token",
["client_id"] = Environment.GetEnvironmentVariable("XTRM_CLIENT_ID")!,
["client_secret"] = Environment.GetEnvironmentVariable("XTRM_CLIENT_SECRET")!,
["refresh_token"] = "YOUR_REFRESH_TOKEN",
});
var response = await client.PostAsync("https://xapisandbox.xtrm.com/oAuth/token", form);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
String form = "grant_type=refresh_token"
+ "&client_id=" + URLEncoder.encode(System.getenv("XTRM_CLIENT_ID"), StandardCharsets.UTF_8)
+ "&client_secret=" + URLEncoder.encode(System.getenv("XTRM_CLIENT_SECRET"), StandardCharsets.UTF_8)
+ "&refresh_token=" + URLEncoder.encode("YOUR_REFRESH_TOKEN", StandardCharsets.UTF_8);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://xapisandbox.xtrm.com/oAuth/token"))
.header("Content-Type", "application/x-www-form-urlencoded")
.header("Accept", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());<?php
$ch = curl_init('https://xapisandbox.xtrm.com/oAuth/token');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'grant_type' => 'refresh_token',
'client_id' => getenv('XTRM_CLIENT_ID'),
'client_secret' => getenv('XTRM_CLIENT_SECRET'),
'refresh_token' => 'YOUR_REFRESH_TOKEN',
]),
CURLOPT_HTTPHEADER => [
'Content-Type: application/x-www-form-urlencoded',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));The renewal response has the same fields as the response to a password grant. Read the access_token from it and use it from then on; it's a new token only if your previous one had expired. Keep the refresh_token from this response for your next renewal.
A refresh_token lasts 60 days, and a password grant works at any time. If a refresh_token grant returns 400 with invalid_grant, get a new token with grant_type=password instead; see Token lifetime and expiry.
#Send the token with every request
Every endpoint except /oAuth/token expects the access token in the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKENThat includes the batch payment endpoints. Send the same token with every call until it expires, rather than requesting one for each call. A request with a JSON body also sends Content-Type: application/json; a GET request sends only the bearer header. For a first call with your token, see the Quickstart.
#When authentication fails
Every endpoint runs the same token and IP address checks. A token problem returns 401 with a body of the form {"error": "…", "error_message": "…"}:
| Condition | Response |
|---|---|
No Authorization header | 401, invalid_authorization: Authorization is missing |
The scheme isn't Bearer | 401, invalid_authentication_type: The authentication type should be bearer |
| Empty token | 401, invalid_credentials: Missing credentials |
| An unrecognized or revoked token, a token that a newer token for the same credentials has replaced, or a call from an IP address that isn't on your company's allowlist | 401, invalid_authorization: Not authorized to view/access this resource |
| Expired token that is still your current token, from an allowlisted address | 401, invalid_token: The Token has expired. Get a new token. |
A batch payment whose IssuerAccountNumber your token isn't allowed to act for | 401, Key Unauthorized: Not authorized to access this resource. |
A status request for a batch submitted under an IssuerAccountNumber your token can't act for | 401, {"StatusCode":401,"Message":"Not authorized to access this resource."} |
Xtrm checks the token before anything else, and it doesn't process or queue any work without a valid one. A failed token request gets 400 with a body of the form {"error": "…", "error_description": "…"}, for example invalid_credentials when the client credentials aren't valid, or invalid_grant for a refresh_token Xtrm doesn't accept. Check the HTTP status, and make sure the response contains an access_token before you store it. See Authentication errors for every case.
If authentication isn't working, check these first:
| Check | Why |
|---|---|
The token URL is https://xapisandbox.xtrm.com/oAuth/token | The token endpoint sits at the host root, not under /API/v4. |
| The token request body is form-encoded | /oAuth/token is the only endpoint that takes application/x-www-form-urlencoded; every other request with a body sends JSON. |
client_id and client_secret are in every token request | Both are required for the password and the refresh_token grant. |
The header reads Authorization: Bearer <access_token> | Every endpoint other than /oAuth/token expects a bearer token. |
| The token is less than 24 hours old | An access_token expires 24 hours after it's issued, however often you use it. Get a new one with grant_type=refresh_token or grant_type=password. |
| You call from an approved IP address | You request allowlisted IPs on the Get Credentials screen, and Xtrm approves them. A call from any other address gets 401 invalid_authorization, the same response as an unrecognized token, so rule this out. |
| Your credentials match the environment | The sandbox is completely separate from your production account. Use the credentials from your sandbox company account with the sandbox host. |
#Resend a request after a token error
A request rejected with 401 isn't processed: Xtrm stores nothing from it. What to do depends on the error:
- After
invalid_token, get a new token and send the same request again. For a batch payment, keep the sameCustomerBatchIdandCustomerTransactionIdvalues, so Xtrm can match it to anything an earlier request stored and never pays twice. See A safe retry pattern. - After
KeyUnauthorized, use credentials that can act forIssuerAccountNumber. A new token for the same credentials gets the same response. - After
invalid_authorization, fetch the current token and make sure you call from an approved IP address.
#Recommended token handling
These are recommendations for your integration, not rules the API enforces:
- Reuse one token. Request a token once and send it with every call until you renew it, rather than requesting a new token for each call.
- Track the expiry. Store
.expiresnext to the token, get a new token once that time has passed, and keep therefresh_tokenfrom each token response. - Renew in one place. If several processes or servers share a token, let one of them renew it and share the result, so they don't race to renew it at the same time.
- Fall back to a new session. If a renewal fails, request a new token with
grant_type=password. - Protect both tokens. Treat the
access_tokenandrefresh_tokenlike passwords: keep them on your server, out of URLs, logs and error messages, and send them over HTTPS only. - Protect your credentials. Keep
client_idandclient_secretin environment variables or a secrets manager. If you think your secret or a token has leaked, contact [email protected].
#Next steps
Use your token to create your first batch payment in the sandbox.
GuideCreate a batch paymentPay many recipients in one request and track the status of each payment.
Batch paymentsRetries & idempotencyResubmit a batch payment safely with your CustomerBatchId and CustomerTransactionId.
Flat JSON and 202 Accepted for batch payments, and the envelope the other endpoints use.
Core conceptsErrorsHow failures are reported, and what each error code means.
API referenceToken endpoint referenceAll parameters and the response for POST /oAuth/token.