Skip to main content
We’re making several changes to the Pagos APIs on September 1, 2026 that will require you to take action. Each change is independent of one another and you can address them in any order. You must complete all required actions before September 1, 2026.

Unified API Keys

All API users must replace all legacy product keys with a new unified key and switch to Authorization: Bearer

New API domains

BIN Data API users must send all requests to bin.pagos.ai

New static IP addresses

BIN Data API users who allowlist IPs must update their allowlist to the new addresses

Batch download URLs

BIN Data Batch users must move to the new domain and allowlist the new download hostname
Important Notes:
  • These changes are independent of one another and must be addressed independently
  • Migrating to the new domain doesn’t migrate your API key, and creating a unified API key doesn’t move you to the new domain
  • Check each section below against your integration

​
Migration Checklist

If you’re impacted by all impending integration changes, complete this entire checklist before September 1, 2026:
1

Create a unified API key

Create a key on the main API Keys tab in the Pagos Service Panel—not under a product-specific tab. Details below.
2

Switch to Bearer authentication

Remove any legacy headers (x-api-key, x-client-key, x-date) and replace them with Authorization: Bearer <api key>.
3

Update your endpoint URLs

Replace parrot.prod.pagosapi.com with bin.pagos.ai in production and parrot.sandbox.pagosapi.com with bin.sandbox.pagos.ai in sandbox.
4

Allowlist the new IP addresses

Add 13.248.157.210 and 166.117.218.160 to any firewall rules.
5

Check how you handle batch download URLs

Use the url value returned in the batch response as-is, rather than rebuilding it from a hardcoded domain. If you allowlist that download hostname anywhere, add the new one before September 1.
6

Revoke your legacy keys

Once production is stable on the unified key, revoke the old product-specific keys.

​
Unified API Keys

Pagos originally issued a separate API key for each product, each with its own authentication format. The unified API key replaces all of them: one key that works across the entire Pagos suite and authenticates with a standard Authorization: Bearer header. You must update your existing keys to the unified API key by September 1. If either of the following is true, you have legacy API keys that must be updated:
  • Your integration sends the API key in an x-api-key header (BIN Data APIs)
  • Your integration sends x-client-key and x-date headers with an HMAC signature (Account Updater and Network Tokenization)
  • You created the key under a product-specific tab in the developer settings of your Pagos account
This is the most common source of confusion.In the settings dropdown menu, click API Keys under Developers. The first tab on this page is API Keys; this is where you can generate unified API keys. The other tabs (Data Ingestion & Observability API, BIN Data API, and Action API) still issue legacy keys, which will stop working on September 1, 2026.If you create a replacement key under a product tab, you haven’t migrated. Always use the main API Keys tab.
API Keys Unified vs Legacy
The Action API tab only appears if your organization signed up for Account Updater or Network Tokenization, so you may not see all three tabs.

​
Creating a Unified Key

Follow the instructions in the Pagos API Authentication guide to generate your new unified API key. All unified keys begin with the prefix ak_. A single key covers every Pagos product your organization is entitled to, so most integrations replace several product keys with one.
API keys are different for Test and Live Mode. Create one in each mode using the environment toggle in the top-right corner of the Service Panel.

​
Switching Your Authentication Header

Send only one authentication header with each request; if a request includes both Authorization and a legacy x-api-key header, Pagos will validate the x-api-key value and ignore the other.

​
Account Updater and Network Tokenization

If your integration uses Account Updater or Network Tokenization, the legacy authentication involved generating an HMAC signature and sending it with x-client-key and x-date headers. With the unified key, replace all three headers with a single Authorization: Bearer <api key> header. You can remove the HMAC signature generation code entirely. Real-Time Account Updater (RTAU): When using a unified API key, message encryption is no longer required. You can remove the Request Key and Response Key encryption steps from your integration if you choose. This is optional; we’ll still accept encrypted payloads. Batch Account Updater: PGP encryption of the batch request and response files is still required regardless of which key type you use. Only the authentication header changes.

​
New API Domains

The BIN Data APIs have moved to new domains: While both legacy and new domains work today, the legacy domains will be retired on September 1, 2026.
Your API key type and endpoint are independent. While both legacy and unified API keys authenticate against both domains during this transition time, both the legacy API keys and legacy domains will be retired on September 1, 2026. See Unified API Keys to update your API keys.

​
New Static IP Addresses

The new domains resolve to new static IP addresses. If you allowlist Pagos traffic in a firewall, add these:
  • 13.248.157.210
  • 166.117.218.160
The legacy domains continue to resolve to their original addresses (99.83.189.213 and 75.2.25.63) until they’re retired on September 1, 2026. Keep both sets allowlisted while you’re mid-migration, and remove the legacy pair once you’ve fully cut over.

​
Batch Download URLs

Responses from the BIN Data Batch /batch/files endpoint contain a url field pointing at the file to download. Today, that URL still references the legacy domain even when you call the new one:
This is expected. On September 1, 2026, these URLs switch to the new domain:
This switch happens on our side (server side), with no release required from you. That being said, check your code to ensure you use the returned url exactly as given, rather than extracting the path and appending it to a hardcoded domain. Integrations that follow the returned URL pick up the new domain automatically.

​
Update Network Controls

If you allowlist the download URLs you get back from the BIN Data Batch API, downloads will start failing on September 1, 2026. Following the URL dynamically isn’t enough on its own, as the hostname inside it changes on that date. Any egress firewall rule, outbound proxy allowlist, or URL filter that permits parrot.prod.pagosapi.com for downloads must also permit bin.pagos.ai before September 1. This is easy to miss, because nothing in your own code changes and the failure appears without a deploy. Check for the download hostname in:
  • Outbound proxy or egress firewall rules
  • URL or domain allowlists on a corporate network
  • Any allowlist maintained by a data platform or ETL tool that fetches the file on your behalf
Add bin.pagos.ai (production) and bin.sandbox.pagos.ai (sandbox) alongside your existing entry now and remove the legacy hostname after the cutover. If you allowlist by IP rather than hostname, add the new IP addresses.
Pass the preSignedUrl value through unchanged. It contains a temporary, expiring token, and its internal structure may change over time; don’t decode, parse, or build logic around its contents.

​
What Doesn’t Change

  • Request and response formats - Apart from the batch url domain described above, no field is added, removed, or reformatted by this migration; switching to a unified key has no effect on response bodies
  • Other headers - Account Updater and Network Tokenization still require X-Merchant-ID, unchanged
  • Batch AU file encryption - Batch Account Updater still requires PGP encryption of request and response files
  • Paths and query parameters - Only the domain changes; /bins, /batch/files, and every other path stays the same
  • Rate limits and entitlements - Your unified key inherits the product access your organization already has

​
Troubleshooting

Usually a key sent in the wrong header. Pagos chooses how to validate your key based on the header you use, and doesn’t fall back to the other:
  • x-api-key is always validated as a legacy key
  • Authorization: Bearer is always validated as a unified key
A unified key sent as x-api-key, or a legacy key sent as Authorization: Bearer, fails even though the key itself is valid. Confirm the key type and header match.Also confirm the key matches the environment you’re calling. Test Mode keys don’t authenticate production requests.
Your request reached a BIN Data API endpoint with no recognized authentication header. Confirm you’re sending Authorization: Bearer <api key> and that the header isn’t being stripped by a proxy or gateway in front of your integration.
Check which tab you created it under. Keys created on the BIN Data API, Action API, or Data Ingestion & Observability API tabs are legacy keys and won’t authenticate with Authorization: Bearer. Create the key on the main API Keys tab instead. See the image in the Unified API Keys section above for further clarification.
Legacy keys only ever authenticate the single product they were issued for, so an integration calling several Pagos APIs may be holding one legacy key per product. A unified key covers every product your organization is entitled to.If a unified key is rejected by one product specifically, your organization may not have access to it; contact your Pagos Account Manager.
Check your firewall rules. The new domains resolve to different IP addresses than the legacy ones.
This is most likely caused by a network allowlist. From September 1, 2026, the url returned by /batch/files points at bin.pagos.ai instead of parrot.prod.pagosapi.com. If an egress firewall, outbound proxy, or URL filter only permits the legacy hostname, the download is blocked even though your integration is behaving correctly and nothing was deployed.Follow the steps under Update Network Controls to add bin.pagos.ai to the allowlist.
Pagos displays a key’s value only once, at creation. If you didn’t store it, revoke that key and generate a replacement.

​
Frequently Asked Questions

If it’s a legacy key, yes. Which domain you call and which key type you use are two separate things. A legacy key authenticates against the new domain today, but it stops working everywhere on September 1, 2026. Check whether your key is legacy using the guidance above.
Legacy API keys stop authenticating requests, and the legacy domains stop serving traffic. Requests using either begin to fail. Batch download URLs also start returning the new domain from that date forward.
No, that’s the point of the change. One unified key authenticates every product your organization is entitled to. You do still need separate keys for Test Mode and Live Mode.
Yes, until September 1, 2026. Both authenticate during the transition, so you can migrate one service or environment at a time. Send only one authentication header per request.
Only the batch download url domain (starting September 1, 2026). Switching your key or your endpoint has no effect on response bodies. If you’re seeing another difference, it isn’t caused by this migration; contact support@pagos.ai and we’ll look into it.
As many as you need. Separate keys per environment, service, or team make it easier to rotate or revoke one without disrupting everything else.
Still have questions about migrating? Email support@pagos.ai.