Skip to main content
Each entry is one release. When a change needs something from you, the entry starts with what to do. Follow the RSS feed to hear about the next one.
​

​
Fiat payments in review, and beneficiary details to correct

Check type before reading holdId in requiredActions, and in required_actions of the transaction.action_required webhook. They used to list only documents to upload, each with a holdId. They can now also hold a beneficiary_details action, which has no holdId, on a LOCKED payout that is already debited.

​
Fiat payments in review

A fiat payout or deposit can be held for review. A held payout answers 202 and nothing is debited. A deposit in review isn’t credited until it’s approved. If we need a document, the transaction moves to ACTION_REQUIRED and you upload it the same way as for any held payment.

​
Correct a payout’s beneficiary details

Before sending a fiat payout, or when the bank refuses it, our operations team can ask you to correct its beneficiary details. The payout stays LOCKED and its amount stays reserved. We send transaction.action_required and an email to your organization, and the payout’s requiredActions lists the fields to correct with a note from our operations team. Send the corrected fields, and our operations team sends the payout. The beneficiary is updated for your next payouts too.POST /v1/transactions/{id}/beneficiary-details · Reference · Guide

​
Also

  • Starting verification for an organization that is blocked or was rejected answers 409 verification_closed. Start verification
​

​
Held payments, reports and SWIFT copies

  • Treat a 202 on a payout or transfer as accepted, not failed, and don’t send it again.
  • Add ACTION_REQUIRED wherever you map transaction statuses.
  • If your webhook endpoint subscribes to a list of eventTypes, add transaction.action_required, report.ready and report.failed.

​
Payments held for review

A fiat payout, crypto payout or Nxosnet transfer can be held for review. The request answers 202 with the held transaction, and nothing is debited yet.When we need an invoice, proof of source of funds or details about the counterparty, the transaction moves to ACTION_REQUIRED and we send transaction.action_required. Upload the files through the API: PDF, PNG or JPEG, up to 20 MB, up to 5 per document type.
  1. POST /v1/transactions/{id}/documents creates the upload and returns a link.
  2. Send the file to that link.
  3. POST …/documents/{documentId}/complete tells us it’s there.

​
Reports

Get the dashboard’s documents through the API: account and transaction statements (PDF or CSV), balance certificates, bank confirmation letters and the monthly statements. Request a report, wait for report.ready, then download it. A broker can request them for a client with Nxos-On-Behalf-Of.POST /v1/reports · GET /v1/reports/{id}/download · Reports guide

​
SWIFT copy of a payout

Download the bank’s SWIFT message (pacs.008, as a PDF) for a completed SWIFT payout. It’s the proof to send a recipient who says the money hasn’t arrived. Each copy can be downloaded a limited number of times, so download it once and keep it.GET /v1/transactions/{id}/swift-copy · Reference

​
Also

  • Each asset in GET /v1/assets has swappableTo, the assets it converts into.
  • Executing a quote on a balance that’s too low answers 400 insufficient_funds, and the quote becomes FAILED.
  • Send Content-Type: application/json with every JSON body. Without it, the request can be refused with 400 invalid_request.
  • Every endpoint in the reference lists the errors it can return, with a real example of each. Errors
​

​
Compliance checks and adjustments

  • Transactions come back as CREDIT_ADJUSTMENT instead of ADJUSTMENT. Update your code and handle the new DEBIT_ADJUSTMENT.
  • A blocked beneficiary’s blockReason is COMPLIANCE_CHECK instead of ADDRESS_SCREENING.
  • A crypto beneficiary’s address can’t be changed. To pay a new address, archive the beneficiary and create a new one.

​
Compliance checks on transactions

Payouts, trades and Nxosnet transfers go through compliance checks before they run. A refused one answers 409 transaction_blocked. A new crypto beneficiary can be BLOCKED as soon as it’s created.

​
Credit and debit adjustments

ADJUSTMENT is renamed CREDIT_ADJUSTMENT, and the new DEBIT_ADJUSTMENT is money we take back: a credit booked in error, or a residual balance when an account closes. Its details give the kind and a reason. ADJUSTMENT still works as a type filter. List transactions

​
Also

  • PATCH on a beneficiary ignores walletAddress.
  • With Nxos-On-Behalf-Of, a broker can read a client’s balances and history whatever the client’s status, as long as the authorization isn’t revoked. Cross-org access
  • organization.verification.updated can carry REJECTED: final, the organization can’t verify again.
​

​
List the assets you can receive

GET /v1/assets lists the assets your organization can receive, with their scale and whether they’re already enabled. Pass any of them to POST /v1/funding-methods to get deposit details. Brokers can list a client’s assets with Nxos-On-Behalf-Of.List assets

​
Also

​
Issue a sign-up link locked to one customer’s email. The customer can only sign up with that address, and the new organization is attributed to you. Asking again for the same email renews the link. You can also list your shared referral links and how many sign-ups each brought.POST /v1/referral-invites · GET /v1/referral-links · Sign-up links guide

​
Also

  • A quote below the minimum or above the maximum size for its pair answers 400 trade_size_out_of_bounds, with both limits in the message. Create a quote
​

​
Bank details while a named account opens

Don’t show deposit details while detailsStatus is PENDING. List the funding methods again later rather than fetching this one by ID.
Bank funding methods have detailsStatus. While your named account for the currency is being opened it’s PENDING, and the account number, IBAN, beneficiary name, address and reference are null. Once the account is open, the details arrive on a new NAMED funding method that replaces this one.Funding methods

​
Also

  • A fiat deposit under review can show up as EXPECTED before it settles.
​

​
Blocked beneficiaries stay

Archiving a BLOCKED beneficiary answers 409 beneficiary_blocked.
​

​
Verification required everywhere

Handle 403 verification_required, and finish verification before you call anything else.
Until your organization’s verification is APPROVED, every endpoint except /v1/organizations/verification* answers 403 verification_required.Verification guide

​
Also

  • Brokers can choose the tier the clients they create start on, with GET and PUT /v1/sub-org-tiers/default. Clients already on a tier don’t move. Broker pricing
​

​
Purpose codes on fiat payouts

Send purpose on every fiat payout. It’s optional while integrations migrate and will become required.
Fiat payouts take a purpose, an ISO 20022 purpose code sent with the wire. Send the one that describes the payment, not a fixed default. GET /v1/transactions/fiat-payouts/options lists the accepted codes with a label to show your users.Payout options

​
Also

  • Fiat payouts have swiftUetr, the reference correspondent banks use to trace a wire, once the payout settles. Initiate a fiat payout
​

​
Deposits under review stay hidden

A fiat deposit held for review isn’t returned by the API until it’s credited. The first transaction.status.updated you receive for it is COMPLETED.
​

​
Sandbox faucet needs an approved organization

The sandbox faucet answers 403 verification_required until your organization’s verification is APPROVED.
​

​
Pricing tiers for your clients

List the tiers agreed with you and put a client you created on one. A tier sets the spread the client is quoted and the share of it you earn, from their next quote. A client reading its own organization sees its tier without your share.GET /v1/sub-org-tiers · PUT /v1/organizations/sub-org-tier · Broker pricing

​
Also

  • Bank funding methods have accountModel. NAMED is an account in your organization’s own name, with its own IBAN and no reference to quote. SHARED is pooled, and the reference must be on the transfer. Funding methods