Changelog

Create a virtual account for an existing customer

You can now create a virtual account for an existing customer who doesn't have a wallet yet.

Virtual account provider is optional

provider_name is now optional when you create a virtual account. In test mode, the only provider you can name is duplo; in live mode, globus or wema.

Virtual accounts

You can now create dedicated NGN virtual accounts and collect bank transfers into them.

• Single-use accounts accept one payment and expire at the time you set, up to 24 hours ahead.
• Multi-use accounts stay open and accept repeated payments.
• List your virtual accounts, find one by its reference or your source reference, and list the transactions paid into it.

Start with the virtual accounts guide or the create virtual account endpoint.

Customer wallet fields use camelCase

The wallet object in customer responses now always has these fields: id, accountName, accountNumber, type, category, status, currency, provider, businessId and walletId.

What you need to do

Read wallet details from the camelCase fields, for example walletId and accountNumber.

See the customers guide.

Exchange rates return buy and sell rates

The exchange rates endpoint response changed:

• buyRate, sellRate, rateType and rateKind were added.
• currentRate is now the buy or sell rate, depending on rateKind.
• previousRate was removed.

What you need to do

Stop reading previousRate. Use buyRate and sellRate for the rate you need.

See the rates guide.

FX swap webhooks follow the swap's progress

FX swap webhooks are now sent as Atlas processes the swap, instead of at the moment you initiate it.

What you need to do

Use the swap response to confirm a swap was created, and webhooks to learn when it completes.

Opay on checkout

Customers can now pay with Opay on the hosted checkout page.

See the checkout guide.

Amounts are always positive

amount is now always a positive number in transaction, payout, checkout, card, payment link and FX swap responses. Use the transaction type to tell money in from money out.

What you need to do

If you relied on a negative amount for outflows, use the transaction type instead.

Checkout redirects fall back to your redirect URL

When a checkout has no redirect_url, customers are now sent to the redirect URL set on your account after they pay. Atlas adds checkoutReference to the query string so you can match the customer to the checkout.

https://example.com/payment-complete?checkoutReference=CHK_123456

Creating a customer requires `type` and `has_wallet`

Creating a customer has new requirements:

• type is required: individual or business.
• has_wallet is required: true or false.
• Disposable email addresses are rejected.
• Customer endpoints are available to NGN businesses only.

What you need to do

Send type and has_wallet on every create customer request, and use a real email address for each customer.

{
  "type": "individual",
  "first_name": "Ada",
  "last_name": "Okafor",
  "email": "ada@example.com",
  "phone": "+2348012345678",
  "has_wallet": false
}

More customer fields

When you create a customer:

• business customers take a business_name,
• wallet_va_name sets the name on the customer's wallet account,
• provider_name chooses the wallet provider (globus or wema), and
• first and last names can be up to 250 characters.

Customer responses now include businessName and type. firstName and lastName return an empty string instead of null when not set.

Bank list updates

The bank list now includes NomBank. Amucha MFB has been removed.

Pay-ins include the sender's details

Pay-in webhooks and pay-in responses now fill in the sender's details for bank inflows: customerAccountName, customerAccountNumber, customerBankName and sessionId. Before this fix, these fields could be empty.

API key mode must match your account

Atlas now rejects requests where the API key's mode doesn't match your account's mode:

• a test key on an account in live mode, or
• a live key on an account in test mode.

The API returns 401 with a message telling you which key to use.

What you need to do

Use test keys while your account is in test mode, and switch to live keys when it goes live. See the authentication guide.

Pay-ins show which account received the funds

Pay-in webhooks and pay-in responses now include a recipient object with the name and number of the account that was credited.

"recipient": {
  "accountName": "Ada Okafor",
  "accountNumber": "8012345678"
}

Either field is null when the provider does not return it. See the webhook events reference.

Checkout webhooks use `event_type`

Checkout webhooks now send the event name in event_type, like every other Atlas webhook. The eventType field introduced on 22 May 2026 is no longer sent.

{
  "event_type": "CHECKOUT_COMPLETED",
  "data": { "...": "..." }
}

What you need to do

Read event_type from checkout webhooks. If you read eventType, switch to event_type.

See the webhooks guide.

Cancel a pending FX swap

You can now cancel an FX swap that has not completed by sending POST /api/v1/tx/swap/{swapId}/cancel. Cancelled swaps return status: cancelled and a reason.

More ways to look up a checkout

New checkout endpoints:

• verify a checkout by reference,
• verify a checkout by source reference, and
• list a checkout's transactions by reference.

Dedicated checkout webhooks

Checkout payments now send a dedicated checkout webhook, with the checkout in the payload. The pay-in webhook is no longer sent for payments made through checkout.

Checkout webhooks use these events:

• CHECKOUT_PROCESSED: the payment was received and is being processed.
• CHECKOUT_COMPLETED: the checkout was paid.
• CHECKOUT_FAILED: the payment failed or the checkout was cancelled.

On this date the event name was sent in an eventType field. It was renamed on 26 May 2026; see checkout webhooks use event_type.

What you need to do

Handle the checkout events above for checkout payments. Pay-in webhooks still arrive for inflows that are not linked to a checkout.

See the webhooks guide.

Exchange rate filters removed

The exchange rates endpoint no longer applies the page, limit, partner_id, product and rate_type query parameters. They are ignored if you send them.

What you need to do

Filter by from_currency and to_currency, and don't rely on pagination for this endpoint.

FX swap status `canceled` is now `cancelled`

FX swap responses now return cancelled for cancelled swaps, instead of canceled. Swaps also include a reason field explaining a cancellation.

What you need to do

If you compare swap status to canceled, compare to cancelled instead.

{
  "status": "cancelled",
  "reason": "<why the swap was cancelled>"
}

International bank transfers

Send money to bank accounts abroad with international bank transfers.

See the international bank transfers guide.

Bulk name enquiry

Check the account names for several bank accounts in one request with bulk name enquiry. It's useful before a bulk payout.

Bulk payouts

Send several NGN bank transfers in one request with bulk payouts. Atlas accepts the batch with 202 Accepted and processes it in the background.

Track a batch with its status by reference or status by source reference.

See the bulk payouts guide.

Business customers

When you create a customer, you can set type to individual or business. Business customers don't need first_name or last_name.

See the customers guide.

FX swap

You can now convert NGN into USD, EUR or GBP:

• initiate a swap, then get a swap or list your swaps,
• check balances in each currency, and
• view rate history.

Swaps send FX_SWAP_CREATED and FX_SWAP_COMPLETED webhooks. Swaps can be limited to operating hours; outside them, the API returns an error with the next available time.

See the swaps guide.

Payment links API

You can now manage payment links through the API:

• create a payment link,
• list payment links and find one by reference or source reference,
• enable or disable a link, and
• list a link's transactions by reference or source reference.

Links created through the API need a source_reference. If you set an amount, it must be at least 100.

See the payment links guide.

Security improvements

We made security improvements to the Atlas API. No action is needed.

Wallet funding through the API is fixed

Funding your wallet through the API no longer rejects requests from the business that owns the wallet.

Checkout transactions confirm faster

Checkout transactions now show successful as soon as Atlas is notified of the inflow, instead of waiting for the inflow to be fully resolved.

What you need to do

Nothing. If you poll checkout status, you see successful sooner.

Bank codes in the bank list are fixed

The bank list endpoint now returns the correct bank code in bankCode. Before this fix, bankCode held a different value from the bank list.

What you need to do

If you cached the bank list before 30 March 2026, fetch it again.

Checkout amount must be at least 100

The amount you send to initiate a checkout must now be at least 100. Smaller amounts fail validation.

What you need to do

Check amounts before you initiate a checkout, and don't offer checkout for totals under 100.

Checkout payments send checkout events

Pay-in webhooks for payments made through checkout now set event_type to:

• CHECKOUT_COMPLETE when the payment succeeds, or
• CHECKOUT_FAILED when it fails.

Before this change they used IN_FLOW_SUCCESS_EVENT, the same event as other inflows. Pay-ins that are not linked to a checkout still use IN_FLOW_SUCCESS_EVENT. Checkout pay-in payloads also include checkoutReference.

These events were replaced on 22 May 2026; see dedicated checkout webhooks.

What you need to do

If you matched checkout payments on IN_FLOW_SUCCESS_EVENT, also handle CHECKOUT_COMPLETE and CHECKOUT_FAILED.

Exchange rates endpoint

A new endpoint returns current exchange rates for a currency pair.

See the exchange rates endpoint and the rates guide.

`source_reference` is required for checkouts and API payouts

source_reference is now required when you:

• initiate a checkout, and
• create a bank transfer payout through the API.

Requests without it fail validation.

What you need to do

Send your own ID for the request as source_reference, and store it so you can look the record up later.

{
  "amount": 5000,
  "currency": "NGN",
  "source_reference": "order_10234"
}

Look up checkouts and payouts by your source reference

You can now find records using source_reference, the ID you assign when you create them.

• List checkout transactions by source reference.
• Get a payout transaction by source reference.
• List payouts and get a payout by reference.

Payout and transaction responses now include sourceReference.

Card payments on checkout

Customers can now pay by card on the hosted checkout page.

Card payments have to be enabled for your business before they appear on checkout. Contact the Atlas team to turn them on.

See the checkout guide.

Fund your wallet through the API

You can now fund your Atlas wallet through the API. The endpoint is authenticated with your public key.

See the fund wallet endpoint.

Checkout transactions include the session ID

Checkout transaction responses now include sessionId, the session ID the bank assigns to the transfer. Use it to trace a payment with the paying bank.

See the checkout guide.

Atlas is live in Nigeria

Atlas is now available to businesses in Nigeria. You can integrate through the API or work directly in the dashboard.

• Checkout: start a checkout and let customers pay by bank transfer. See the checkout guide.
• Payouts: send NGN to any Nigerian bank account. See the payout quickstart.
• Customers: create, update, blacklist and reactivate the customers you transact with.
• Transactions: list your transactions or look one up by reference.
• Wallets: check your wallet balance.
• Banking: fetch the list of supported banks and confirm an account name before you pay out.