> For the complete documentation index, see [llms.txt](https://developers.unigox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.unigox.com/api-reference/user-management.md).

# User Management

Create and manage your customers, put them through KYC, hold their payout details — and issue the fiat accounts they are paid into.

All of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with the `user_uuid` every route below takes in its path; KYC verifies them; and an account is opened for that same person. There is no second identity to register and no separate customer record for banking — the person Unigox verified is the person the account belongs to.

**Customer-owned wallets and crypto deposits**

1. Ask Unigox to enable external-wallet customers for your partner account.
2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a `partner_wallet` customer. The type is fixed at creation; use the same type when repeating a request for an existing `user_ref`.
3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign` or its equivalent `signMessage` operation.
4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`. `GET` on that path returns the link status and XAI balances.
5. Allocate deposit addresses and check their monitoring status before accepting payments. Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279). Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.

Enabling external-wallet customers controls new customer creation. Existing external-wallet customers can still link their wallet, read it and deposit if that permission is later disabled. These routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use the separate Bridge payment API; the partner deposit-address routes do not attach memos.

## Verify API key authentication

> Verifies that the provided API key is valid and authentication is working correctly.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"ErrorResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["error_key"],"properties":{"error_key":{"type":"string","description":"Standardized error key for client error handling"}}}}}}},"paths":{"/api/v1/partner/verify-auth":{"get":{"tags":["User Management"],"summary":"Verify API key authentication","description":"Verifies that the provided API key is valid and authentication is working correctly.\n","operationId":"verifyAuth","responses":{"200":{"description":"Authentication successful","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string"},"authenticated":{"type":"boolean"}}}}}]}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create or get partner user

> Creates a customer or returns the existing customer for \`user\_ref\`. Use the returned\
> \`user\_uuid\` in subsequent paths. Partners can only access their own users.\
> \
> For customer-owned wallets and deposit-address allocation, set \`wallet\_type: external\_wallet\`\
> and complete the wallet challenge/link steps in User Management. This option must be enabled\
> by Unigox before creating a new external-wallet customer. The default is \`partner\_wallet\`.\
> A customer's wallet type cannot be changed by repeating this request.\
> \
> Each partner user must represent one actual payout beneficiary/end customer. Create a separate partner user for each beneficiary. Do not attach payment details for unrelated people to the same \`user\_uuid\`.\
> \
> A partner user is the SENDER. To pay someone else, do not create a shell user for the payee — register a recipient (\`/api/v1/partner/recipients\`) and quote against it. See the Third-party payouts guide.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"WalletType":{"type":"string","enum":["partner_wallet","external_wallet"],"default":"partner_wallet","description":"Whose address holds this customer's funds, fixed at creation.\n- `partner_wallet` — your partner wallet holds them and you sign (default, and every customer created before this field existed).\n- `external_wallet` — the customer's own EVM address holds them and the customer signs. Requires non-custodial mode.\n"},"CreateUserResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"user_uuid":{"type":"string","format":"uuid","description":"Public UUID of the user. **Use this value in every subsequent call** — it is the\n`{user_uuid}` in `/partner/users/{user_uuid}/…`.\n"},"id":{"type":"string","format":"uuid","description":"The same value as `user_uuid`, kept for integrations written before that name\nexisted. Either can be read; they never differ.\n"},"email":{"type":"string","format":"email"},"kyc_status":{"type":"string","enum":["NOT_INITIATED","IN_PROGRESS","UNDER_REVIEW","VERIFIED","VERIFICATION_REJECTED"]},"wallet_type":{"$ref":"#/components/schemas/WalletType"},"wallet":{"$ref":"#/components/schemas/CustomerWalletSummary"},"created_at":{"type":"string","format":"date-time"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"CustomerWalletSummary":{"type":"object","nullable":true,"required":["address","status"],"description":"Present for `external_wallet` customers, `null` for `partner_wallet` ones.","properties":{"address":{"type":"string","nullable":true,"description":"The linked address in lower case, `null` until linked"},"status":{"type":"string","enum":["unlinked","linked"]}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/users":{"post":{"tags":["User Management"],"summary":"Create or get partner user","description":"Creates a customer or returns the existing customer for `user_ref`. Use the returned\n`user_uuid` in subsequent paths. Partners can only access their own users.\n\nFor customer-owned wallets and deposit-address allocation, set `wallet_type: external_wallet`\nand complete the wallet challenge/link steps in User Management. This option must be enabled\nby Unigox before creating a new external-wallet customer. The default is `partner_wallet`.\nA customer's wallet type cannot be changed by repeating this request.\n\nEach partner user must represent one actual payout beneficiary/end customer. Create a separate partner user for each beneficiary. Do not attach payment details for unrelated people to the same `user_uuid`.\n\nA partner user is the SENDER. To pay someone else, do not create a shell user for the payee — register a recipient (`/api/v1/partner/recipients`) and quote against it. See the Third-party payouts guide.\n","operationId":"createPartnerUser","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_ref","email"],"properties":{"user_ref":{"type":"string","description":"Partner's unique user ID (usually primary key or UUID)"},"email":{"type":"string","format":"email","description":"User's email address. Among your customers created from 2026-10-12, one email is\none account: a second `user_ref` with such an email gets its own `user_uuid` but the\nsame account (funds, orders, KYC and, for `external_wallet`, the same wallet). A new\n`user_ref` with the email of a customer created before that date gets a new account.\nThe same email at another partner or in the Unigox app is a separate account.\n"},"wallet_type":{"$ref":"#/components/schemas/WalletType"}}}}}},"responses":{"200":{"description":"Customer created, or the existing customer for this `user_ref`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserResponse"}}}},"400":{"description":"Bad Request, for example an unknown `wallet_type` (`INVALID_REQUEST`)"},"401":{"description":"Unauthorized (missing or invalid X-API-Key)"},"403":{"description":"`FEATURE_NOT_ENABLED` — `wallet_type: external_wallet` requested but non-custodial mode is not switched on for your partner account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"`WALLET_TYPE_MISMATCH` — a customer with this `user_ref`, or your customer with this email,\nalready exists with a different `wallet_type`. A customer's type is fixed at creation.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"Internal Server Error"}}}}}}
```

## Partner user by ID

> Get user details including KYC status and payment profiles using the user\_uuid returned during user creation. Partners can only access their own users.

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"GetUserResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"user_uuid":{"type":"string","format":"uuid","description":"Public UUID of the user. Use this value in all subsequent API calls."},"email":{"type":"string","format":"email"},"wallet_type":{"$ref":"#/components/schemas/WalletType"},"wallet":{"$ref":"#/components/schemas/CustomerWalletSummary"},"created_at":{"type":"string","format":"date-time"},"kyc":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_INITIATED","IN_PROGRESS","UNDER_REVIEW","VERIFIED","VERIFICATION_REJECTED"],"description":"Current partner-facing KYC status. `UNDER_REVIEW` means the customer is under\nmanual compliance review — not yet cleared, and unlike `IN_PROGRESS` (automated,\nusually a couple of minutes) it can take up to 24 hours. The internal review\nstate name is never exposed.\n"},"kyc_method":{"type":"string","enum":["direct_data","external_token","handoff"],"description":"KYC submission method used"},"first_name":{"type":"string","description":"User's first name from KYC data"},"last_name":{"type":"string","description":"User's last name from KYC data"},"country_code":{"type":"string","description":"User's country code (ISO 2-letter) from KYC data"},"rejection_reasons":{"type":"array","description":"Reasons from this partner customer's rejected verification session. Empty when not rejected or no reason is available. Also included as data.rejection_reasons by the verification-status endpoint; legacy provider_messages is retained there.","items":{"type":"string"}},"rejection_reason":{"type":"string","nullable":true,"description":"Reason for KYC rejection (if status is VERIFICATION_REJECTED)"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp for KYC status"}}},"fiat_account_issuance":{"type":"object","description":"Whether a fiat account can be opened for this customer, and what the bank is still\nshort of if not. It lives here because there is no second identity to register for\nan account: the gaps are gaps in this customer's KYC record.\n","properties":{"ready":{"type":"boolean","description":"True when `POST /api/v1/partner/fiat-accounts` will be accepted for this customer."},"missing_fields":{"type":"array","items":{"type":"string"},"description":"The fields the bank needs that the KYC record does not have, in the names\n`PATCH /api/v1/partner/users/{user_uuid}/kyc` takes: `address`, `city`,\n`postal_code`, `dob`, `id_number`, `id_type`.\n"}}},"payment_profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rail":{"type":"string"},"currency":{"type":"string"},"institution_name":{"type":"string","nullable":true},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","additionalProperties":true}}}}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"WalletType":{"type":"string","enum":["partner_wallet","external_wallet"],"default":"partner_wallet","description":"Whose address holds this customer's funds, fixed at creation.\n- `partner_wallet` — your partner wallet holds them and you sign (default, and every customer created before this field existed).\n- `external_wallet` — the customer's own EVM address holds them and the customer signs. Requires non-custodial mode.\n"},"CustomerWalletSummary":{"type":"object","nullable":true,"required":["address","status"],"description":"Present for `external_wallet` customers, `null` for `partner_wallet` ones.","properties":{"address":{"type":"string","nullable":true,"description":"The linked address in lower case, `null` until linked"},"status":{"type":"string","enum":["unlinked","linked"]}}}}},"paths":{"/api/v1/partner/users/{user_uuid}":{"get":{"tags":["User Management"],"summary":"Partner user by ID","description":"Get user details including KYC status and payment profiles using the user_uuid returned during user creation. Partners can only access their own users.","operationId":"getPartnerUser","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"User found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found"}}}}}}
```

## Request a wallet ownership challenge

> Returns a Sign-In with Ethereum (EIP-4361) message that proves the customer controls \`address\`.\
> Show it to the customer unchanged and have them sign it with \`personal\_sign\`, then submit it to\
> \`POST /api/v1/partner/users/{user\_uuid}/wallet\`.\
> \
> The message names your partner account, the customer and the address, is valid for 10 minutes\
> and can be used once. Requesting a new challenge invalidates the previous one.\
> \
> Only an externally owned account can be linked: linking needs a plain \`personal\_sign\`\
> signature, and the same key later signs EIP-712 requests that the XAI forwarder verifies with\
> \`ecrecover\`. A smart-contract wallet cannot produce either, so linking one fails with\
> \`400 INVALID\_SIGNATURE\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"parameters":{"UserUUIDPath":{"name":"user_uuid","in":"path","required":true,"description":"The `user_uuid` returned by `POST /api/v1/partner/users`. Partners can only access their own customers.","schema":{"type":"string","format":"uuid"}}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"WalletChallenge":{"type":"object","properties":{"message":{"type":"string","description":"EIP-4361 message to sign with `personal_sign`, unchanged"},"nonce":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/wallet/challenge":{"post":{"tags":["User Management"],"summary":"Request a wallet ownership challenge","description":"Returns a Sign-In with Ethereum (EIP-4361) message that proves the customer controls `address`.\nShow it to the customer unchanged and have them sign it with `personal_sign`, then submit it to\n`POST /api/v1/partner/users/{user_uuid}/wallet`.\n\nThe message names your partner account, the customer and the address, is valid for 10 minutes\nand can be used once. Requesting a new challenge invalidates the previous one.\n\nOnly an externally owned account can be linked: linking needs a plain `personal_sign`\nsignature, and the same key later signs EIP-712 requests that the XAI forwarder verifies with\n`ecrecover`. A smart-contract wallet cannot produce either, so linking one fails with\n`400 INVALID_SIGNATURE`.\n","operationId":"createWalletChallenge","parameters":[{"$ref":"#/components/parameters/UserUUIDPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"The customer's EVM address"}}}}}},"responses":{"201":{"description":"Challenge issued","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WalletChallenge"}}}]}}}},"400":{"description":"`INVALID_REQUEST` — `address` is not a valid EVM address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"`CUSTOMER_NOT_FOUND` — no customer with this `user_uuid` belongs to your partner account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"`WALLET_ALREADY_LINKED` — the customer is already linked, or the address is linked to another of your customers. Addresses that Unigox holds for an account (a Unigox app wallet, your partner wallet, an escrow) or uses itself are refused the same way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"`WALLET_TYPE_MISMATCH` — the customer is a `partner_wallet` customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Customer wallet and balance

> The customer's linked address, its status, and the balance held at that address on the XAI\
> chain in each supported token. Deposits appear here once credited on XAI.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"parameters":{"UserUUIDPath":{"name":"user_uuid","in":"path","required":true,"description":"The `user_uuid` returned by `POST /api/v1/partner/users`. Partners can only access their own customers.","schema":{"type":"string","format":"uuid"}}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"CustomerWallet":{"type":"object","required":["address","status","linked_at","chain_id","balances"],"properties":{"address":{"type":"string","nullable":true,"description":"The linked address in lower case"},"status":{"type":"string","enum":["unlinked","linked"]},"linked_at":{"type":"string","format":"date-time","nullable":true},"chain_id":{"type":"string","description":"Chain where the balance is held (XAI)"},"balances":{"type":"array","description":"Balance at the linked address on XAI for USDT and USDC. Empty until linked. On `POST …/wallet` also empty when the balance could not be read at that moment; `GET …/wallet` answers `502 BALANCE_UNAVAILABLE` instead. Amounts drop trailing zeros. Compare token addresses case-insensitively.","items":{"type":"object","properties":{"crypto_currency":{"type":"string"},"token_address":{"type":"string"},"amount_human":{"type":"string"},"decimals":{"type":"integer"}}}}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/wallet":{"get":{"tags":["User Management"],"summary":"Customer wallet and balance","description":"The customer's linked address, its status, and the balance held at that address on the XAI\nchain in each supported token. Deposits appear here once credited on XAI.\n","operationId":"getCustomerWallet","parameters":[{"$ref":"#/components/parameters/UserUUIDPath"}],"responses":{"200":{"description":"Wallet returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerWallet"}}}]}}}},"404":{"description":"`CUSTOMER_NOT_FOUND` — no customer with this `user_uuid` belongs to your partner account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"`WALLET_TYPE_MISMATCH` — the customer is a `partner_wallet` customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"502":{"description":"`BALANCE_UNAVAILABLE` — the XAI balance could not be read. Safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Link the customer's address

> Submit the challenge message and the customer's \`personal\_sign\` signature. The signer is\
> recovered on the server and must equal \`address\`; the message must be the one issued, unchanged\
> and unexpired.\
> \
> On success the address is the customer's address at Unigox for good: deposits credit it,\
> off-ramp orders are funded from it, on-ramp orders and refunds are paid to it. It cannot be\
> changed or unlinked. A \`wallet.linked\` webhook is sent once, without retries.\
> \
> \`balances\` in the response is empty when the XAI balance could not be read at that moment;\
> that is not a zero balance. Read \`GET .../wallet\` again for it.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"parameters":{"UserUUIDPath":{"name":"user_uuid","in":"path","required":true,"description":"The `user_uuid` returned by `POST /api/v1/partner/users`. Partners can only access their own customers.","schema":{"type":"string","format":"uuid"}}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"CustomerWallet":{"type":"object","required":["address","status","linked_at","chain_id","balances"],"properties":{"address":{"type":"string","nullable":true,"description":"The linked address in lower case"},"status":{"type":"string","enum":["unlinked","linked"]},"linked_at":{"type":"string","format":"date-time","nullable":true},"chain_id":{"type":"string","description":"Chain where the balance is held (XAI)"},"balances":{"type":"array","description":"Balance at the linked address on XAI for USDT and USDC. Empty until linked. On `POST …/wallet` also empty when the balance could not be read at that moment; `GET …/wallet` answers `502 BALANCE_UNAVAILABLE` instead. Amounts drop trailing zeros. Compare token addresses case-insensitively.","items":{"type":"object","properties":{"crypto_currency":{"type":"string"},"token_address":{"type":"string"},"amount_human":{"type":"string"},"decimals":{"type":"integer"}}}}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/wallet":{"post":{"tags":["User Management"],"summary":"Link the customer's address","description":"Submit the challenge message and the customer's `personal_sign` signature. The signer is\nrecovered on the server and must equal `address`; the message must be the one issued, unchanged\nand unexpired.\n\nOn success the address is the customer's address at Unigox for good: deposits credit it,\noff-ramp orders are funded from it, on-ramp orders and refunds are paid to it. It cannot be\nchanged or unlinked. A `wallet.linked` webhook is sent once, without retries.\n\n`balances` in the response is empty when the XAI balance could not be read at that moment;\nthat is not a zero balance. Read `GET .../wallet` again for it.\n","operationId":"linkCustomerWallet","parameters":[{"$ref":"#/components/parameters/UserUUIDPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","message","signature"],"properties":{"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"message":{"type":"string","description":"The `message` from the challenge, byte for byte"},"signature":{"type":"string","description":"65-byte `personal_sign` signature, hex with 0x prefix"}}}}}},"responses":{"200":{"description":"Address linked","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerWallet"}}}]}}}},"400":{"description":"`INVALID_SIGNATURE` — the signature does not recover to `address`, the message was altered, or `address` differs from the challenged one. `INVALID_REQUEST` — a malformed address or body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"`CUSTOMER_NOT_FOUND` — no customer with this `user_uuid` belongs to your partner account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"`WALLET_ALREADY_LINKED`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"410":{"description":"`CHALLENGE_EXPIRED` — no challenge was issued, it is older than 10 minutes, or it was already used. A message from a challenge that a newer one replaced fails as `400 INVALID_SIGNATURE`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"`WALLET_TYPE_MISMATCH` — the customer is a `partner_wallet` customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## List customer deposit addresses and monitoring status

> Returns the saved deposit addresses for a customer with a linked external wallet.\
> The customer must belong to the authenticated partner. This request checks monitoring\
> status for existing addresses; it never allocates another address.\
> Complete the external-wallet customer creation and wallet-link steps in User Management first.\
> Deposits credit that linked wallet on UNIGOX, on XAI (chain ID 660279), and are reported\
> by the \`wallet.deposit.received\` partner webhook.\
> \
> After an allocation returns \`503 DEPOSIT\_ADDRESS\_NOT\_WATCHED\`, repeat this GET to check\
> the saved addresses. Do not repeat the allocation POST to check readiness.\
> \
> For EVM and Tron, accept payments only on networks whose \`monitoring.chains\` entry has\
> \`confirmed: true\`. A missing network is unconfirmed. \`monitoring.watched\` is the\
> aggregate result, so one network can be ready while another is still pending.\
> For Solana and TON, use \`monitoring.watched\`; their \`chains\` array is empty.\
> Monitoring confirmation does not establish which tokens are supported.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerDepositAddressesResponse":{"type":"object","required":["success","data"],"description":"Successful address allocation or retrieval; readiness is separate from HTTP success.","properties":{"success":{"type":"boolean","enum":[true],"description":"The allocation or list request completed successfully."},"data":{"type":"object","required":["deposit_addresses"],"properties":{"deposit_addresses":{"type":"array","description":"Saved addresses for the requested customer; listing may return an empty array.","items":{"$ref":"#/components/schemas/PartnerDepositAddress"}}}}}},"PartnerDepositAddress":{"type":"object","required":["chain_type","address","monitoring"],"description":"One saved customer deposit address with its monitoring result.","properties":{"chain_type":{"type":"string","enum":["evm","svm","tvm","ton"],"description":"Address family; svm is Solana and tvm is Tron."},"address":{"type":"string","description":"The saved collection address. Allocation and subsequent lists retain this address."},"monitoring":{"$ref":"#/components/schemas/PartnerDepositAddressMonitoring"}}},"PartnerDepositAddressMonitoring":{"type":"object","required":["watched","chains"],"description":"Monitoring result for this saved address. A false or missing confirmation means\nunconfirmed, not proof that monitoring is absent. Older responses without monitoring\nmetadata are returned as `watched: false` and `chains: []`.\n\nEVM and Tron report each network independently. Solana confirms address registration\nwith Helius. TON monitors saved addresses without an external registration step;\nits confirmation is not a live service-health check. Solana and TON return `chains: []`.\n","properties":{"watched":{"type":"boolean","description":"Whether monitoring is confirmed for all required networks of this address.\nFor EVM and Tron, use the per-network confirmations when selecting a payment network.\n"},"chains":{"type":"array","description":"Per-network confirmations for EVM and Tron. Missing networks are unconfirmed.","items":{"type":"object","required":["chainId","confirmed"],"properties":{"chainId":{"type":"integer","format":"int64","minimum":1,"description":"Numeric chain identifier of the network being checked."},"confirmed":{"type":"boolean","description":"Whether this address's monitoring is confirmed on that network."}}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/deposit-addresses":{"get":{"tags":["User Management"],"summary":"List customer deposit addresses and monitoring status","description":"Returns the saved deposit addresses for a customer with a linked external wallet.\nThe customer must belong to the authenticated partner. This request checks monitoring\nstatus for existing addresses; it never allocates another address.\nComplete the external-wallet customer creation and wallet-link steps in User Management first.\nDeposits credit that linked wallet on UNIGOX, on XAI (chain ID 660279), and are reported\nby the `wallet.deposit.received` partner webhook.\n\nAfter an allocation returns `503 DEPOSIT_ADDRESS_NOT_WATCHED`, repeat this GET to check\nthe saved addresses. Do not repeat the allocation POST to check readiness.\n\nFor EVM and Tron, accept payments only on networks whose `monitoring.chains` entry has\n`confirmed: true`. A missing network is unconfirmed. `monitoring.watched` is the\naggregate result, so one network can be ready while another is still pending.\nFor Solana and TON, use `monitoring.watched`; their `chains` array is empty.\nMonitoring confirmation does not establish which tokens are supported.\n","operationId":"listPartnerCustomerDepositAddresses","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The customer user_uuid belonging to the authenticated partner.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Saved addresses with current monitoring results; an empty list is valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerDepositAddressesResponse"}}}},"401":{"description":"Missing or invalid X-API-Key."},"404":{"description":"`CUSTOMER_NOT_FOUND` — no customer with this `user_uuid` belongs to your partner account."},"409":{"description":"`WALLET_NOT_LINKED` — the customer has no linked address yet."},"422":{"description":"`WALLET_TYPE_MISMATCH` — the customer is a `partner_wallet` customer."},"502":{"description":"`DEPOSIT_ADDRESSES_UNAVAILABLE` — saved addresses could not be read; this GET never allocates. Safe to retry."}}}}}}
```

## Allocate customer deposit addresses

> Creates additional deposit addresses for a customer with a linked external wallet.\
> The customer must belong to the authenticated partner. Supported address families are\
> \`evm\`, \`svm\` (Solana), \`tvm\` (Tron) and \`ton\`. The configured address cap also applies.\
> First create an \`external\_wallet\` customer and complete the wallet challenge/link flow.\
> The linked address receives the supported settlement token on UNIGOX, on XAI (chain ID 660279).\
> \`wallet.deposit.received\` reports the amount and token actually credited.\
> \
> \`201\` confirms allocation; use each address's \`monitoring\` fields to select a confirmed\
> payment network. \`503 DEPOSIT\_ADDRESS\_NOT\_WATCHED\` means allocation may already have\
> completed, but monitoring is not confirmed. Its \`data.deposit\_addresses\` preserves\
> the addresses returned by the allocation. Keep those addresses and check them with\
> GET \`/api/v1/partner/users/{user\_uuid}/deposit-addresses\`; do not repeat this POST.\
> An empty saved-address list in a 503 response does not prove that nothing was allocated.\
> \
> \`502 DEPOSIT\_ADDRESS\_ALLOCATION\_UNKNOWN\` means the allocation outcome could not be\
> confirmed after sending the request. Check saved addresses with the same GET; do not\
> automatically repeat this allocation. An immediate empty list does not prove failure,\
> because the original request may still complete. The allocation POST is not idempotent:\
> repeating it can create additional addresses. Treat a lost HTTP response as uncertain too.\
> \
> These partner endpoints do not attach a memo. Wallet-signed memo-address requests\
> use the separate Bridge payment API.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"PartnerDepositAddressesResponse":{"type":"object","required":["success","data"],"description":"Successful address allocation or retrieval; readiness is separate from HTTP success.","properties":{"success":{"type":"boolean","enum":[true],"description":"The allocation or list request completed successfully."},"data":{"type":"object","required":["deposit_addresses"],"properties":{"deposit_addresses":{"type":"array","description":"Saved addresses for the requested customer; listing may return an empty array.","items":{"$ref":"#/components/schemas/PartnerDepositAddress"}}}}}},"PartnerDepositAddress":{"type":"object","required":["chain_type","address","monitoring"],"description":"One saved customer deposit address with its monitoring result.","properties":{"chain_type":{"type":"string","enum":["evm","svm","tvm","ton"],"description":"Address family; svm is Solana and tvm is Tron."},"address":{"type":"string","description":"The saved collection address. Allocation and subsequent lists retain this address."},"monitoring":{"$ref":"#/components/schemas/PartnerDepositAddressMonitoring"}}},"PartnerDepositAddressMonitoring":{"type":"object","required":["watched","chains"],"description":"Monitoring result for this saved address. A false or missing confirmation means\nunconfirmed, not proof that monitoring is absent. Older responses without monitoring\nmetadata are returned as `watched: false` and `chains: []`.\n\nEVM and Tron report each network independently. Solana confirms address registration\nwith Helius. TON monitors saved addresses without an external registration step;\nits confirmation is not a live service-health check. Solana and TON return `chains: []`.\n","properties":{"watched":{"type":"boolean","description":"Whether monitoring is confirmed for all required networks of this address.\nFor EVM and Tron, use the per-network confirmations when selecting a payment network.\n"},"chains":{"type":"array","description":"Per-network confirmations for EVM and Tron. Missing networks are unconfirmed.","items":{"type":"object","required":["chainId","confirmed"],"properties":{"chainId":{"type":"integer","format":"int64","minimum":1,"description":"Numeric chain identifier of the network being checked."},"confirmed":{"type":"boolean","description":"Whether this address's monitoring is confirmed on that network."}}}}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}},"PartnerDepositAddressPendingResponse":{"type":"object","required":["success","error","data"],"description":"Monitoring is unconfirmed; returned addresses remain saved and must not be reallocated.","properties":{"success":{"type":"boolean","enum":[false],"description":"Monitoring confirmation did not complete."},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["DEPOSIT_ADDRESS_NOT_WATCHED"],"description":"Allocation may have completed, but monitoring was not confirmed."},"message":{"type":"string","description":"Explanation of the pending monitoring result."}}},"data":{"type":"object","required":["deposit_addresses"],"properties":{"deposit_addresses":{"type":"array","description":"Saved addresses returned by the allocation. An empty array does not prove no allocation occurred.","items":{"$ref":"#/components/schemas/PartnerDepositAddress"}}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/deposit-addresses/{chainType}/allocate":{"post":{"tags":["User Management"],"summary":"Allocate customer deposit addresses","description":"Creates additional deposit addresses for a customer with a linked external wallet.\nThe customer must belong to the authenticated partner. Supported address families are\n`evm`, `svm` (Solana), `tvm` (Tron) and `ton`. The configured address cap also applies.\nFirst create an `external_wallet` customer and complete the wallet challenge/link flow.\nThe linked address receives the supported settlement token on UNIGOX, on XAI (chain ID 660279).\n`wallet.deposit.received` reports the amount and token actually credited.\n\n`201` confirms allocation; use each address's `monitoring` fields to select a confirmed\npayment network. `503 DEPOSIT_ADDRESS_NOT_WATCHED` means allocation may already have\ncompleted, but monitoring is not confirmed. Its `data.deposit_addresses` preserves\nthe addresses returned by the allocation. Keep those addresses and check them with\nGET `/api/v1/partner/users/{user_uuid}/deposit-addresses`; do not repeat this POST.\nAn empty saved-address list in a 503 response does not prove that nothing was allocated.\n\n`502 DEPOSIT_ADDRESS_ALLOCATION_UNKNOWN` means the allocation outcome could not be\nconfirmed after sending the request. Check saved addresses with the same GET; do not\nautomatically repeat this allocation. An immediate empty list does not prove failure,\nbecause the original request may still complete. The allocation POST is not idempotent:\nrepeating it can create additional addresses. Treat a lost HTTP response as uncertain too.\n\nThese partner endpoints do not attach a memo. Wallet-signed memo-address requests\nuse the separate Bridge payment API.\n","operationId":"allocatePartnerCustomerDepositAddresses","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The customer user_uuid belonging to the authenticated partner.","schema":{"type":"string","format":"uuid"}},{"name":"chainType","in":"path","required":true,"description":"Address family; EVM addresses can support multiple configured networks.","schema":{"type":"string","enum":["evm","svm","tvm","ton"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":50,"default":1,"description":"Number of additional addresses. Omitted or zero requests one address."}}}}}},"responses":{"201":{"description":"Addresses allocated; monitoring is reported for each saved address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerDepositAddressesResponse"}}}},"400":{"description":"`INVALID_REQUEST` — the request body is not valid JSON."},"401":{"description":"Missing or invalid X-API-Key."},"404":{"description":"`CUSTOMER_NOT_FOUND` — no customer with this `user_uuid` belongs to your partner account."},"409":{"description":"`WALLET_NOT_LINKED` — the customer has no linked address yet."},"422":{"description":"`INVALID_REQUEST` — unknown `chainType`, or `count` above 50 or below 0. `WALLET_TYPE_MISMATCH` — the customer is a `partner_wallet` customer."},"429":{"description":"`ADDRESS_CAP_REACHED` — allocating would take the customer past the limit for this chain type; `error.message` states the limit."},"502":{"description":"DEPOSIT_ADDRESS_ALLOCATION_UNKNOWN means the allocation may have committed.\nCheck saved addresses; do not automatically repeat the allocation.\nDEPOSIT_ADDRESSES_UNAVAILABLE covers other failures, including a failed address\ncount before allocation was attempted.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"503":{"description":"DEPOSIT_ADDRESS_NOT_WATCHED preserves any returned allocation while monitoring is\nunconfirmed.\n","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PartnerDepositAddressPendingResponse"},{"$ref":"#/components/schemas/PartnerErrorResponse"}]}}}}}}}}}
```

## Quote a withdrawal

> Prices a withdrawal of \`amount\` of \`crypto\_currency\` from the customer's XAI address to\
> \`destination\_address\` on \`destination\_chain\`, and returns the EIP-712 \`ForwardRequest\` that\
> authorizes it. Have the customer sign \`forward\_request\` unchanged with their linked key, then\
> submit it to \`POST /api/v1/partner/users/{user\_uuid}/withdrawals\` before \`expires\_at\`.\
> \
> The token arriving is the same \`crypto\_currency\`. Destination chains for a token:\
> \`GET /api/v1/partner/send-out/routes?crypto=\<crypto\_currency>\`. \`destination\_chain: xai\` sends\
> on XAI itself with no bridge.\
> \
> The quote is valid for 10 minutes; the signed request's \`deadline\` equals \`expires\_at\`.\
> Withdrawals need no KYC.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"parameters":{"UserUUIDPath":{"name":"user_uuid","in":"path","required":true,"description":"The `user_uuid` returned by `POST /api/v1/partner/users`. Partners can only access their own customers.","schema":{"type":"string","format":"uuid"}}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"WithdrawalQuote":{"type":"object","properties":{"withdrawal_quote_id":{"type":"string","format":"uuid"},"expires_at":{"type":"string","format":"date-time"},"crypto_currency":{"type":"string"},"amount":{"type":"string","description":"Debited from the customer's XAI balance, with the token's full precision"},"to_amount":{"type":"string","description":"Estimated amount arriving, in the destination token's decimals"},"fee":{"type":"string","description":"Bridge and network cost, in `crypto_currency`; `\"0.000000\"` for `xai`"},"destination_chain":{"type":"string"},"destination_address":{"type":"string"},"forward_request":{"type":"object","description":"EIP-712 `ForwardRequest` to sign unchanged","properties":{"from":{"type":"string","description":"The customer's linked address"},"to":{"type":"string","description":"Token contract on XAI"},"value":{"type":"string"},"gas":{"type":"string","description":"Always `\"500000\"`"},"nonce":{"type":"string"},"deadline":{"type":"string","description":"Unix seconds; equals `expires_at`"},"data":{"type":"string","description":"ERC-20 `transfer` calldata"}}},"eip712_domain":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"chainId":{"type":"string"},"verifyingContract":{"type":"string","description":"The XAI forwarder"}}}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/withdrawals/quote":{"post":{"tags":["User Management"],"summary":"Quote a withdrawal","description":"Prices a withdrawal of `amount` of `crypto_currency` from the customer's XAI address to\n`destination_address` on `destination_chain`, and returns the EIP-712 `ForwardRequest` that\nauthorizes it. Have the customer sign `forward_request` unchanged with their linked key, then\nsubmit it to `POST /api/v1/partner/users/{user_uuid}/withdrawals` before `expires_at`.\n\nThe token arriving is the same `crypto_currency`. Destination chains for a token:\n`GET /api/v1/partner/send-out/routes?crypto=<crypto_currency>`. `destination_chain: xai` sends\non XAI itself with no bridge.\n\nThe quote is valid for 10 minutes; the signed request's `deadline` equals `expires_at`.\nWithdrawals need no KYC.\n","operationId":"quoteCustomerWithdrawal","parameters":[{"$ref":"#/components/parameters/UserUUIDPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["crypto_currency","amount","destination_chain","destination_address"],"properties":{"crypto_currency":{"type":"string"},"amount":{"type":"string","description":"Amount to debit from the customer's XAI balance, decimal string with no more decimals than the token has"},"destination_chain":{"type":"string","description":"Chain name as `GET /api/v1/partner/send-out/routes` lists it (case-insensitive), its `chain_id`, or `xai`"},"destination_address":{"type":"string","description":"Address on the destination chain, in that chain's format"}}}}}},"responses":{"201":{"description":"Withdrawal quoted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WithdrawalQuote"}}}]}}}},"400":{"description":"`INVALID_REQUEST` — a missing field, an unsupported chain or token, a malformed destination address, a destination the chain cannot pay (`error.details.reason`), or an amount with too many decimals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"`CUSTOMER_NOT_FOUND` — no customer with this `user_uuid` belongs to your partner account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"`WALLET_NOT_LINKED` — the customer has no linked address yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"`INSUFFICIENT_BALANCE`, `WALLET_TYPE_MISMATCH`, or `AMOUNT_TOO_LOW` — too small to bridge to that chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR` — the balance or the forwarder nonce could not be read. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"503":{"description":"`BRIDGE_UNAVAILABLE` — no bridge quote could be obtained for this destination. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## GET /api/v1/partner/users/{user\_uuid}/withdrawals

> List the customer's withdrawals

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"parameters":{"UserUUIDPath":{"name":"user_uuid","in":"path","required":true,"description":"The `user_uuid` returned by `POST /api/v1/partner/users`. Partners can only access their own customers.","schema":{"type":"string","format":"uuid"}}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"CustomerWithdrawal":{"type":"object","properties":{"withdrawal_id":{"type":"string","format":"uuid","description":"Equals `withdrawal_quote_id`"},"withdrawal_quote_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["submitted","bridging","completed","failed","needs_review"],"description":"`submitted` — accepted for submission; `bridging` — executed on XAI, on its way to the destination chain;\n`completed` — arrived; `failed` — did not take effect on XAI (reverted, or not executed before the quote's\ndeadline), the funds are still on the customer's address; `needs_review` — could not be settled automatically (for example the bridge\nfailed after the funds left XAI, or still open after 24 hours), Unigox reconciles it.\n"},"crypto_currency":{"type":"string"},"amount":{"type":"string"},"to_amount":{"type":"string"},"destination_chain":{"type":"string"},"destination_address":{"type":"string"},"source_tx_hash":{"type":"string","nullable":true,"description":"Transaction on XAI"},"destination_tx_hash":{"type":"string","nullable":true,"description":"Transaction on the destination chain, once known"},"failure_reason":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/withdrawals":{"get":{"tags":["User Management"],"summary":"List the customer's withdrawals","operationId":"listCustomerWithdrawals","parameters":[{"$ref":"#/components/parameters/UserUUIDPath"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Withdrawals, newest first","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"withdrawals":{"type":"array","items":{"$ref":"#/components/schemas/CustomerWithdrawal"}},"total":{"type":"integer"}}}}}]}}}},"404":{"description":"`CUSTOMER_NOT_FOUND` — no customer with this `user_uuid` belongs to your partner account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"`WALLET_NOT_LINKED` — the customer has no linked address yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"`WALLET_TYPE_MISMATCH` — the customer is a `partner_wallet` customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Submit a signed withdrawal

> Submit the quoted \`forward\_request\` and the customer's signature. Unigox checks that the request\
> is exactly the one quoted (sender, token, calldata, gas, nonce, deadline), that it was signed by\
> the customer's linked address, re-checks the balance, and relays it; the customer pays no gas.\
> The withdrawal keeps the quote's id: \`withdrawal\_id\` equals \`withdrawal\_quote\_id\`.\
> \
> Safe to retry with the same \`withdrawal\_quote\_id\`: a quote is executed at most once, and a\
> repeat returns the existing withdrawal.\
> \
> Off-ramp funding and withdrawals share the customer's forwarder nonce. Once one of them executes,\
> a request signed with the same nonce can no longer execute and answers \`409 QUOTE\_EXPIRED\`;\
> request a new quote.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"parameters":{"UserUUIDPath":{"name":"user_uuid","in":"path","required":true,"description":"The `user_uuid` returned by `POST /api/v1/partner/users`. Partners can only access their own customers.","schema":{"type":"string","format":"uuid"}}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"CustomerWithdrawal":{"type":"object","properties":{"withdrawal_id":{"type":"string","format":"uuid","description":"Equals `withdrawal_quote_id`"},"withdrawal_quote_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["submitted","bridging","completed","failed","needs_review"],"description":"`submitted` — accepted for submission; `bridging` — executed on XAI, on its way to the destination chain;\n`completed` — arrived; `failed` — did not take effect on XAI (reverted, or not executed before the quote's\ndeadline), the funds are still on the customer's address; `needs_review` — could not be settled automatically (for example the bridge\nfailed after the funds left XAI, or still open after 24 hours), Unigox reconciles it.\n"},"crypto_currency":{"type":"string"},"amount":{"type":"string"},"to_amount":{"type":"string"},"destination_chain":{"type":"string"},"destination_address":{"type":"string"},"source_tx_hash":{"type":"string","nullable":true,"description":"Transaction on XAI"},"destination_tx_hash":{"type":"string","nullable":true,"description":"Transaction on the destination chain, once known"},"failure_reason":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/withdrawals":{"post":{"tags":["User Management"],"summary":"Submit a signed withdrawal","description":"Submit the quoted `forward_request` and the customer's signature. Unigox checks that the request\nis exactly the one quoted (sender, token, calldata, gas, nonce, deadline), that it was signed by\nthe customer's linked address, re-checks the balance, and relays it; the customer pays no gas.\nThe withdrawal keeps the quote's id: `withdrawal_id` equals `withdrawal_quote_id`.\n\nSafe to retry with the same `withdrawal_quote_id`: a quote is executed at most once, and a\nrepeat returns the existing withdrawal.\n\nOff-ramp funding and withdrawals share the customer's forwarder nonce. Once one of them executes,\na request signed with the same nonce can no longer execute and answers `409 QUOTE_EXPIRED`;\nrequest a new quote.\n","operationId":"createCustomerWithdrawal","parameters":[{"$ref":"#/components/parameters/UserUUIDPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["withdrawal_quote_id","forward_request","signature"],"properties":{"withdrawal_quote_id":{"type":"string","format":"uuid"},"forward_request":{"type":"object","description":"The `forward_request` from the quote, unchanged"},"signature":{"type":"string","description":"EIP-712 signature by the customer's linked address, hex with 0x prefix"}}}}}},"responses":{"202":{"description":"Withdrawal accepted and being sent on chain (`status: submitted`)","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerWithdrawal"}}}]}}}},"400":{"description":"`INVALID_REQUEST` — the request differs from the quote or is not signed by the customer; `error.message` names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"404":{"description":"`CUSTOMER_NOT_FOUND` or `WITHDRAWAL_NOT_FOUND` (unknown `withdrawal_quote_id`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"`QUOTE_EXPIRED` — the quote expired, the forwarder nonce moved, or another withdrawal has not executed on XAI yet. `WALLET_NOT_LINKED` — the customer has no linked address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"`INSUFFICIENT_BALANCE` (the balance dropped since the quote), or `WALLET_TYPE_MISMATCH` (a `partner_wallet` customer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR` — the balance or the forwarder nonce could not be read. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## GET /api/v1/partner/users/{user\_uuid}/withdrawals/{withdrawal\_id}

> Withdrawal by ID

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"parameters":{"UserUUIDPath":{"name":"user_uuid","in":"path","required":true,"description":"The `user_uuid` returned by `POST /api/v1/partner/users`. Partners can only access their own customers.","schema":{"type":"string","format":"uuid"}}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"CustomerWithdrawal":{"type":"object","properties":{"withdrawal_id":{"type":"string","format":"uuid","description":"Equals `withdrawal_quote_id`"},"withdrawal_quote_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["submitted","bridging","completed","failed","needs_review"],"description":"`submitted` — accepted for submission; `bridging` — executed on XAI, on its way to the destination chain;\n`completed` — arrived; `failed` — did not take effect on XAI (reverted, or not executed before the quote's\ndeadline), the funds are still on the customer's address; `needs_review` — could not be settled automatically (for example the bridge\nfailed after the funds left XAI, or still open after 24 hours), Unigox reconciles it.\n"},"crypto_currency":{"type":"string"},"amount":{"type":"string"},"to_amount":{"type":"string"},"destination_chain":{"type":"string"},"destination_address":{"type":"string"},"source_tx_hash":{"type":"string","nullable":true,"description":"Transaction on XAI"},"destination_tx_hash":{"type":"string","nullable":true,"description":"Transaction on the destination chain, once known"},"failure_reason":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PartnerErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Machine-readable error code. Possible values:\n- `QUOTE_EXPIRED` — quote TTL has passed; for a customer withdrawal, also the customer's forwarder nonce moved or another withdrawal has not executed yet (request a new quote)\n- `QUOTE_NOT_FOUND` — quote ID does not exist\n- `QUOTE_ALREADY_USED` — quote was already consumed by initiate. `details.order_id` names the order it created, so a retried initiate whose first response was lost can continue with that order\n- `PRICE_CHANGED_REQUOTE` — price changed beyond slippage tolerance, partner should request a new quote\n- `ORDER_NOT_FOUND` — order ID does not exist or belongs to another partner\n- `NO_OFFERS_AVAILABLE` — no vendor offers for the requested pair\n- `INVALID_REQUEST` — malformed request or missing fields\n- `INVALID_PAYMENT_DETAILS` — payment details not found or invalid\n- `RAIL_ROUTE_MISMATCH` — rail or route does not match payment details (self-payout only; on a third-party payout a mismatched `rail` is `THIRD_PARTY_CONTEXT_INVALID`)\n- `UNAUTHORIZED` — authentication failed\n- `INTERNAL_ERROR` — unexpected server error\n- `INVALID_STATUS` — order is not in the correct status for the requested action\n- `TRANSACTOR_ERROR` — (502) the transaction could not be submitted, although the signed request passed every check, or a refund could not be executed; retry\n- `INSUFFICIENT_BALANCE` — the funding wallet (your partner wallet, or the `external_wallet` customer's address) lacks tokens for the escrow or withdrawal\n- `OPERATION_NOT_ALLOWED` — action is not permitted for the current order state\n- `KYC_NOT_CLEARED` — the customer is not KYC-cleared for this transaction; `error.details.kyc_status` carries their current partner-facing status\n- `FEATURE_NOT_ENABLED` — non-custodial mode is not switched on for your partner account\n- `WALLET_NOT_LINKED` — the `external_wallet` customer has no linked address yet\n- `WALLET_ALREADY_LINKED` — the customer is already linked, the address is linked to another of your customers, or Unigox holds it for an account (a Unigox app wallet, your partner wallet, an escrow) or uses it itself\n- `WALLET_TYPE_MISMATCH` — the call does not apply to this customer's `wallet_type`\n- `INVALID_SIGNATURE` — a wallet challenge signature does not recover to the address, or the message was altered\n- `CHALLENGE_EXPIRED` — no wallet challenge was issued, it is older than 10 minutes, already used, or replaced by a newer one\n- `CUSTOMER_NOT_FOUND` / `WITHDRAWAL_NOT_FOUND` — unknown customer or withdrawal on the customer wallet routes\n- `ADDRESS_CAP_REACHED` — allocating would take the customer past the deposit-address limit for that chain type\n- `BALANCE_UNAVAILABLE` / `DEPOSIT_ADDRESSES_UNAVAILABLE` — a dependency did not answer; safe to retry\n- `AMOUNT_TOO_LOW` — (422) too small to bridge to the destination chain: the bridge refused it (`error.details.reason`), or its fee would exceed 2% (`error.details.bridge_fee`, `estimated_minimum_amount`, `max_fee_pct`)\n- `SENDER_IDENTITY_REQUIRED` — the payout corridor settles consumer-to-consumer and the customer's record cannot name them as the remitter; `error.details.kyc_fields` lists what to send to `PATCH /partner/users/{user_uuid}/kyc`, and `error.details.field_limits` carries the rail's length ceiling on any listed field that has one\n- `RECIPIENT_NOT_FOUND` — (404) the recipient endpoints, and an estimate naming such a recipient or destination: no recipient (or destination) with that id belongs to your partner account, or it was archived. A quote answers the same case `422 THIRD_PARTY_CONTEXT_INVALID`\n- `RECIPIENT_SERVICE_UNAVAILABLE` — (503) the recipient endpoints: the recipient directory could not be reached; retry with backoff\n- `THIRD_PARTY_CONTEXT_INVALID` — (422) the sender, recipient or destination of a third-party payout cannot be used, including a `rail` that is not the destination's and a destination currency that is not `fiat_currency`; the message says which\n- `THIRD_PARTY_RAIL_NOT_SUPPORTED` — (409) the currency is open to recipient payouts, but not over the rail the destination settles on\n- `THIRD_PARTY_PAYOUT_AGENT_NOT_READY` — (409) recipient payouts are switched off on our side; no order is created and the quote stays valid\n- `THIRD_PARTY_RELATIONSHIP_NOT_SUPPORTED` — (422) the rail refuses that beneficiary (a Chinese wallet pays `self` or `family` only)\n- `THIRD_PARTY_SENDER_COUNTRY_NOT_SUPPORTED` — (422) the rail refuses money sent from the country on the customer's verified identity\n- `THIRD_PARTY_PAYOUT_UNDER_REVIEW` — (422, initiate) compliance put the payout in review\n- `THIRD_PARTY_PAYOUT_DECLINED` — (422, initiate) compliance refused the payout\n\nFiat account endpoints (`/partner/fiat-accounts/config` and the `/partner/users/{user_uuid}`\n`identity`, `identification` and `fiat-accounts` routes) answer with their own codes, each\ndescribed on the response that returns it: `FIAT_ACCOUNT_NOT_FOUND`,\n`ACCOUNT_HOLDER_NOT_FOUND`, `ACCOUNT_NOT_PROVISIONED`, `CUSTOMER_NOT_FOUND`,\n`CUSTOMER_NOT_VERIFIED`, `CLIENT_NOT_APPROVED`, `HOLDER_REGISTRATION_IN_PROGRESS`,\n`IDENTIFICATION_MISSING`, `IDENTIFICATION_ALREADY_LINKED`, `INVALID_DOCUMENT_TYPE`,\n`POSTAL_CODE_REQUIRED`, `INVALID_POSTAL_CODE`, `MISSING_FIELDS`, `PRODUCT_NOT_ACTIVATED`,\n`ISSUANCE_NOT_GRANTED`, `ISSUANCE_DISABLED`, `PROVISIONING_IN_PROGRESS`,\n`UNSUPPORTED_CURRENCY`, `UNSUPPORTED_ISSUER_COUNTRY`, `CURRENCY_NOT_PERMITTED`,\n`CURRENCY_NOT_PRICED`, `RECORD_FAILED`, `BANKING_ERROR`, `BANKING_UNAVAILABLE`.\n\nBusiness customer endpoints (`/partner/business-customers`) can also answer\n`KYB_UNAVAILABLE` or `SERVICE_UNAVAILABLE` (5xx): try again shortly.\n\nThis list is not closed: codes are added as endpoints grow. Treat a code you do not recognise\nas an error of the kind its HTTP status says, rather than rejecting the response.\n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","nullable":true,"additionalProperties":true,"description":"Additional context (e.g., quoted_rate, current_rate for slippage errors)"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/withdrawals/{withdrawal_id}":{"get":{"tags":["User Management"],"summary":"Withdrawal by ID","operationId":"getCustomerWithdrawal","parameters":[{"$ref":"#/components/parameters/UserUUIDPath"},{"name":"withdrawal_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Withdrawal returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerWithdrawal"}}}]}}}},"404":{"description":"`CUSTOMER_NOT_FOUND` or `WITHDRAWAL_NOT_FOUND`. A quote that was never submitted is not a withdrawal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"409":{"description":"`WALLET_NOT_LINKED` — the customer has no linked address yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}},"422":{"description":"`WALLET_TYPE_MISMATCH` — the customer is a `partner_wallet` customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerErrorResponse"}}}}}}}}}
```

## Submit KYC data for a partner user

> Submit KYC (Know Your Customer) data for a partner user. Supports three methods:\
> \- direct\_data: Partner submits PII data directly, user is verified\
> \- external\_token: Partner provides external KYC provider credentials (SumSub token or Persona inquiry\_id)\
> \- handoff: Unigox handles KYC verification and generates verification URL\
> \
> \*\*Important for EUR/AUD/GBP off-ramp:\*\* EUR, AUD, and GBP payouts require the user's\
> physical address. Include \`address\`, \`city\`, and \`postal\_code\` in the PII data\
> when submitting KYC. If not provided at submission time, you can add them later with\
> \`PATCH /partner/users/{user\_uuid}/kyc\`. Without address, EUR/AUD/GBP orders will be created\
> with status \`pending\_address\` until the address is provided.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"KYCSubmitDirectData":{"type":"object","required":["method","data"],"properties":{"method":{"type":"string","enum":["direct_data"]},"data":{"type":"object","required":["pii"],"properties":{"pii":{"type":"object","required":["first_name","last_name","country_code"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"country_code":{"type":"string"},"dob":{"type":"string","format":"date","description":"Date of birth (YYYY-MM-DD). Optional, but when provided it must be a real date in the past and indicate an age of at least 18. A future, malformed, or under-18 date is rejected with HTTP 400 (see error responses below)."},"middle_name":{"type":"string"},"phone_number":{"type":"string","description":"E.164 format"},"id_number":{"type":"string","description":"Government identity/registry number. Enables the **NIN/BVN + selfie** verification option: instead of uploading an ID-document image, the customer proves identity with this number plus a live selfie (no ID photo). AiPrise validates the number against the national registry (NIN->NIMC, BVN->NIBSS) and face-matches the selfie against the registry photo. After this submission, upload only a `selfie` (document_type=selfie) to the documents endpoint - verification starts automatically. Supported for the registry number types listed under `id_type`, in the countries those registries cover."},"id_type":{"type":"string","description":"Registry type for `id_number`. For the NIN/BVN + selfie option it must be one of the listed registry types (image-only IDs such as passport/driver licence are NOT accepted - those use the ID-image flow). An unsupported/missing value returns `400 { \"error_key\": \"invalid_identity_number_type\" }`.","enum":["NIN","NIN_SLIP","BVN","NATIONAL_ID","VOTER_ID","TAX_ID","KENYA_KRA_PIN"]},"address":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City. Required for EUR/AUD/GBP offramp (auto-populates into payment details)."},"postal_code":{"type":"string"}}}}}}},"KYCSubmitExternalToken":{"type":"object","required":["method","data"],"properties":{"method":{"type":"string","enum":["external_token"]},"data":{"type":"object","required":["provider"],"description":"Provider-specific fields:\n- SumSub: requires `token` (SumSub share token)\n- Persona: requires `inquiry_id` (Persona inquiry ID, e.g. inq_xxx)\n","properties":{"provider":{"type":"string","enum":["sumsub","persona"],"description":"KYC provider name"},"token":{"type":"string","description":"SumSub share token (required when provider=sumsub)"},"inquiry_id":{"type":"string","description":"Persona inquiry ID (required when provider=persona). This is the inq_xxx identifier returned by Persona when the inquiry was created."}}}}},"KYCSubmitHandoff":{"type":"object","required":["method","data"],"properties":{"method":{"type":"string","enum":["handoff"]},"data":{"type":"object","properties":{"pii":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"country_code":{"type":"string"}}}}}}},"KYCSubmitResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"kyc_status":{"type":"string","enum":["NOT_INITIATED","IN_PROGRESS","UNDER_REVIEW","VERIFIED","VERIFICATION_REJECTED"],"description":"A submission may asynchronously move to `UNDER_REVIEW` (manual compliance review,\nup to 24 hours) via the status endpoint and the `user.kyc.updated` webhook — distinct\nfrom `IN_PROGRESS` (automated, usually a couple of minutes). Treat both as not cleared.\n"},"message":{"type":"string"},"verification_url":{"type":"string","format":"uri","nullable":true,"description":"Verification URL (only returned for handoff method)"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"ErrorResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["error_key"],"properties":{"error_key":{"type":"string","description":"Standardized error key for client error handling"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/kyc-submissions":{"post":{"tags":["User Management"],"summary":"Submit KYC data for a partner user","description":"Submit KYC (Know Your Customer) data for a partner user. Supports three methods:\n- direct_data: Partner submits PII data directly, user is verified\n- external_token: Partner provides external KYC provider credentials (SumSub token or Persona inquiry_id)\n- handoff: Unigox handles KYC verification and generates verification URL\n\n**Important for EUR/AUD/GBP off-ramp:** EUR, AUD, and GBP payouts require the user's\nphysical address. Include `address`, `city`, and `postal_code` in the PII data\nwhen submitting KYC. If not provided at submission time, you can add them later with\n`PATCH /partner/users/{user_uuid}/kyc`. Without address, EUR/AUD/GBP orders will be created\nwith status `pending_address` until the address is provided.\n","operationId":"submitKYC","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/KYCSubmitDirectData"},{"$ref":"#/components/schemas/KYCSubmitExternalToken"},{"$ref":"#/components/schemas/KYCSubmitHandoff"}]}}}},"responses":{"200":{"description":"KYC submitted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KYCSubmitResponse"}}}},"400":{"description":"Bad Request — invalid method, missing required data, or a date of birth that fails validation. The response body is `{ \"success\": false, \"data\": { \"error_key\": \"...\", \"message\": \"...\" } }`. Possible `error_key` values include: `underage_not_allowed` — \"User must be at least 18 years old. The provided date_of_birth indicates an age under 18.\"; and `invalid_date_of_birth` — \"date_of_birth is invalid. Provide a real date in YYYY-MM-DD format that is in the past.\" `invalid_identity_number_type` — \"id_type is required for NIN/BVN + selfie verification and must be one of the supported identity number types (e.g. NIN, BVN).\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found"},"500":{"description":"Internal Server Error"}}}}}}
```

## Upload KYC document for a partner user

> Upload a KYC document for a partner user. Choose one of two upload methods:\
> \
> \---\
> \
> \### Method 1: File Upload\
> Send the document as a file attachment.\
> \`\`\`\
> POST /api/v1/partner/users/{user\_uuid}/kyc/documents\
> Content-Type: multipart/form-data\
> \
> document: \<file>\
> document\_type: identity\_front\
> \`\`\`\
> \
> \### Method 2: Single URL Upload\
> Send a URL pointing to one document image.\
> \`\`\`json\
> {\
> &#x20; "upload\_method": "url\_link",\
> &#x20; "document\_type": "identity\_front",\
> &#x20; "url": "<https://example.com/id-front.jpg"\\>
> }\
> \`\`\`\
> \
> \### Method 3: Batch URL Upload\
> Upload multiple documents in one call (up to 10).\
> \`\`\`json\
> {\
> &#x20; "upload\_method": "url\_link",\
> &#x20; "documents": \[\
> &#x20;   { "document\_type": "identity\_front", "url": "<https://example.com/id-front.jpg>" },\
> &#x20;   { "document\_type": "selfie", "url": "<https://example.com/selfie.jpg>" }\
> &#x20; ]\
> }\
> \`\`\`\
> \
> \*\*URL requirements:\*\* HTTPS only, 10MB per file, JPEG/PNG/GIF/PDF.\
> \
> \---\
> \
> \*\*Supported \`document\_type\` values\*\* — the API accepts exactly the following (this is the\
> complete, finite list; anything else is rejected). \*\*Required:\*\* a \`selfie\` \*\*and\*\* one\
> identity-document front (\`identity\_front\` or any equivalent ID type listed below). All other\
> values are optional (document back sides and alternative ID types).\
> \
> \*\*NIN/BVN + selfie option (verify with a registry number instead of an ID image).\*\* This is a\
> \*\*two-step flow across two endpoints\*\* — the registry number is submitted as \*\*text\*\*, never\
> uploaded as a file:\
> \
> &#x20; 1\. On the \*\*submit-KYC\*\* endpoint (\`POST .../kyc-submissions\`, method \`direct\_data\`), send the\
> &#x20;    customer's data \*\*plus\*\* \`id\_number\` (the registry number, as a string) and \`id\_type\`\
> &#x20;    (e.g. \`NIN\`, \`BVN\`). No image is uploaded in this step.\
> &#x20; 2\. On \*\*this\*\* documents endpoint, upload \*\*only a \`selfie\`\*\* (\`document\_type: selfie\`) — \*\*no\
> &#x20;    ID-document image\*\*. The registry number from step 1 satisfies the identity requirement, so\
> &#x20;    verification starts automatically (national-registry lookup + selfie face-match against the\
> &#x20;    registry photo).\
> \
> The three upload methods below (multipart / single URL / batch URL) are for \*\*image files\*\* only\
> — they are not how the registry number is sent (that is the \`id\_number\` text field in step 1).\
> \
> \`document\_type\` only selects which slot (front / back / selfie) an image occupies. It is \*\*not\*\*\
> used as a document-category and it does \*\*not\*\* set the country: our verification system detects\
> the actual document type from the image, and the country is taken from the customer's KYC profile\
> (their identity/address country), independent of this value. The country names below are naming\
> hints to help you choose — they are not enforced, so a country-specific value is never required.\
> \
> \- Generic identity document — \*\*general\*\* (any country): \`identity\_front\`, \`identity\_back\`\
> \- Passport — \*\*general\*\* (any country): \`passport\`, \`passport\_front\`\
> \- National ID — \*\*general\*\* (any country; covers e.g. Nigeria's NIN card, Kenya national ID,\
> &#x20; India Aadhaar): \`national\_id\`, \`national\_id\_front\`, \`national\_id\_back\`\
> \- Driver license — \*\*general\*\* (any country): \`driver\_license\`, \`driver\_license\_front\`, \`driver\_license\_back\`\
> \- Voter ID — \*\*general\*\* (any country): \`voter\_id\`, \`voter\_id\_front\`, \`voter\_id\_back\`\
> \- Resident card — \*\*general\*\* (any country): \`resident\_card\`, \`resident\_card\_front\`, \`resident\_card\_back\`\
> \- ID card — \*\*general\*\* (any country; catch-all for local cards without their own type below,\
> &#x20; e.g. Indonesia KTP, Pakistan Nadra Card): \`id\_card\`, \`id\_card\_front\`, \`id\_card\_back\`\
> \- Ghana card — \*\*Ghana\*\* (NIA biometric national ID): \`ghana\_card\`, \`ghana\_card\_front\`, \`ghana\_card\_back\`\
> \- Ghana SSNIT card — \*\*Ghana\*\* (social-security card): \`ghana\_ssnit\_card\`, \`ghana\_ssnit\_card\_front\`, \`ghana\_ssnit\_card\_back\`\
> \- Kenya alien card — \*\*Kenya\*\* (non-citizen resident ID): \`kenya\_alien\_card\`, \`kenya\_alien\_card\_front\`, \`kenya\_alien\_card\_back\`\
> \- Green book — \*\*South Africa\*\* (legacy green barcoded ID book): \`green\_book\`, \`green\_book\_front\`, \`green\_book\_back\`\
> \- Tax ID — \*\*general\*\* label (primary example: India PAN card): \`tax\_id\`, \`tax\_id\_front\`, \`tax\_id\_back\`\
> \- Colombia PPT — \*\*Colombia\*\* (Permiso por Protección Temporal): \`colombia\_ppt\`, \`colombia\_ppt\_front\`, \`colombia\_ppt\_back\`\
> \- Selfie — \*\*general\*\* (any country): \`selfie\`\
> \
> Any front-side identity type above (e.g. \`passport\`, \`national\_id\`, \`tax\_id\`) satisfies the ID\
> requirement — not only the literal \`identity\_front\`. \*\*Nigeria's NIN\*\* is submitted as\
> \`national\_id\` (with the customer's country set to Nigeria); there is no separate \`nin\` value.\
> \
> \*\*Automatic Verification:\*\* After an identity document + \`selfie\` + KYC data are present, the\
> service queues verification processing and returns immediately. The identity document can be\
> any accepted ID type above, not only \`identity\_front\` (e.g. \`passport\` + \`selfie\` triggers\
> verification). A \`200\` response means the documents were accepted; it is not a final\
> verification result. Asynchronous verification checks can move the user to\
> \`VERIFICATION\_REJECTED\` after this response.\
> \
> To trigger verification explicitly, or to check exactly what is still missing, call\
> \`POST /api/v1/partner/users/{user\_uuid}/kyc/verify\` (below).\
> \
> Obtain the eventual outcome by polling\
> \`GET /api/v1/partner/users/{user\_uuid}/verification-status\` or consuming the\
> \`user.kyc.updated\` webhook. The upload response does not include a verification session ID\
> or \`kyc\_status\`, because asynchronous state can change immediately after acceptance.<br>

````json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"KycDocumentType":{"type":"string","description":"Complete set of document types accepted by the partner KYC upload endpoint. `document_type` only selects the upload slot (front/back/selfie); it is not a document-category and does not set the country — our verification system detects the document type from the image, and the country comes from the customer's KYC profile. Values named after a country (`ghana_card`, `ghana_ssnit_card`, `kenya_alien_card`, `green_book`, `colombia_ppt`) are country-specific hints; all others (`passport`, `national_id`, `driver_license`, `voter_id`, `resident_card`, `id_card`, `tax_id`, `identity_front`/`identity_back`, `selfie`) are general — any country. Nigeria's NIN is submitted as `national_id`.","enum":["identity_front","identity_back","selfie","passport","passport_front","national_id","national_id_front","national_id_back","driver_license","driver_license_front","driver_license_back","voter_id","voter_id_front","voter_id_back","resident_card","resident_card_front","resident_card_back","id_card","id_card_front","id_card_back","ghana_card","ghana_card_front","ghana_card_back","ghana_ssnit_card","ghana_ssnit_card_front","ghana_ssnit_card_back","kenya_alien_card","kenya_alien_card_front","kenya_alien_card_back","green_book","green_book_front","green_book_back","tax_id","tax_id_front","tax_id_back","colombia_ppt","colombia_ppt_front","colombia_ppt_back"]}}},"paths":{"/api/v1/partner/users/{user_uuid}/kyc/documents":{"post":{"tags":["User Management"],"summary":"Upload KYC document for a partner user","description":"Upload a KYC document for a partner user. Choose one of two upload methods:\n\n---\n\n### Method 1: File Upload\nSend the document as a file attachment.\n```\nPOST /api/v1/partner/users/{user_uuid}/kyc/documents\nContent-Type: multipart/form-data\n\ndocument: <file>\ndocument_type: identity_front\n```\n\n### Method 2: Single URL Upload\nSend a URL pointing to one document image.\n```json\n{\n  \"upload_method\": \"url_link\",\n  \"document_type\": \"identity_front\",\n  \"url\": \"https://example.com/id-front.jpg\"\n}\n```\n\n### Method 3: Batch URL Upload\nUpload multiple documents in one call (up to 10).\n```json\n{\n  \"upload_method\": \"url_link\",\n  \"documents\": [\n    { \"document_type\": \"identity_front\", \"url\": \"https://example.com/id-front.jpg\" },\n    { \"document_type\": \"selfie\", \"url\": \"https://example.com/selfie.jpg\" }\n  ]\n}\n```\n\n**URL requirements:** HTTPS only, 10MB per file, JPEG/PNG/GIF/PDF.\n\n---\n\n**Supported `document_type` values** — the API accepts exactly the following (this is the\ncomplete, finite list; anything else is rejected). **Required:** a `selfie` **and** one\nidentity-document front (`identity_front` or any equivalent ID type listed below). All other\nvalues are optional (document back sides and alternative ID types).\n\n**NIN/BVN + selfie option (verify with a registry number instead of an ID image).** This is a\n**two-step flow across two endpoints** — the registry number is submitted as **text**, never\nuploaded as a file:\n\n  1. On the **submit-KYC** endpoint (`POST .../kyc-submissions`, method `direct_data`), send the\n     customer's data **plus** `id_number` (the registry number, as a string) and `id_type`\n     (e.g. `NIN`, `BVN`). No image is uploaded in this step.\n  2. On **this** documents endpoint, upload **only a `selfie`** (`document_type: selfie`) — **no\n     ID-document image**. The registry number from step 1 satisfies the identity requirement, so\n     verification starts automatically (national-registry lookup + selfie face-match against the\n     registry photo).\n\nThe three upload methods below (multipart / single URL / batch URL) are for **image files** only\n— they are not how the registry number is sent (that is the `id_number` text field in step 1).\n\n`document_type` only selects which slot (front / back / selfie) an image occupies. It is **not**\nused as a document-category and it does **not** set the country: our verification system detects\nthe actual document type from the image, and the country is taken from the customer's KYC profile\n(their identity/address country), independent of this value. The country names below are naming\nhints to help you choose — they are not enforced, so a country-specific value is never required.\n\n- Generic identity document — **general** (any country): `identity_front`, `identity_back`\n- Passport — **general** (any country): `passport`, `passport_front`\n- National ID — **general** (any country; covers e.g. Nigeria's NIN card, Kenya national ID,\n  India Aadhaar): `national_id`, `national_id_front`, `national_id_back`\n- Driver license — **general** (any country): `driver_license`, `driver_license_front`, `driver_license_back`\n- Voter ID — **general** (any country): `voter_id`, `voter_id_front`, `voter_id_back`\n- Resident card — **general** (any country): `resident_card`, `resident_card_front`, `resident_card_back`\n- ID card — **general** (any country; catch-all for local cards without their own type below,\n  e.g. Indonesia KTP, Pakistan Nadra Card): `id_card`, `id_card_front`, `id_card_back`\n- Ghana card — **Ghana** (NIA biometric national ID): `ghana_card`, `ghana_card_front`, `ghana_card_back`\n- Ghana SSNIT card — **Ghana** (social-security card): `ghana_ssnit_card`, `ghana_ssnit_card_front`, `ghana_ssnit_card_back`\n- Kenya alien card — **Kenya** (non-citizen resident ID): `kenya_alien_card`, `kenya_alien_card_front`, `kenya_alien_card_back`\n- Green book — **South Africa** (legacy green barcoded ID book): `green_book`, `green_book_front`, `green_book_back`\n- Tax ID — **general** label (primary example: India PAN card): `tax_id`, `tax_id_front`, `tax_id_back`\n- Colombia PPT — **Colombia** (Permiso por Protección Temporal): `colombia_ppt`, `colombia_ppt_front`, `colombia_ppt_back`\n- Selfie — **general** (any country): `selfie`\n\nAny front-side identity type above (e.g. `passport`, `national_id`, `tax_id`) satisfies the ID\nrequirement — not only the literal `identity_front`. **Nigeria's NIN** is submitted as\n`national_id` (with the customer's country set to Nigeria); there is no separate `nin` value.\n\n**Automatic Verification:** After an identity document + `selfie` + KYC data are present, the\nservice queues verification processing and returns immediately. The identity document can be\nany accepted ID type above, not only `identity_front` (e.g. `passport` + `selfie` triggers\nverification). A `200` response means the documents were accepted; it is not a final\nverification result. Asynchronous verification checks can move the user to\n`VERIFICATION_REJECTED` after this response.\n\nTo trigger verification explicitly, or to check exactly what is still missing, call\n`POST /api/v1/partner/users/{user_uuid}/kyc/verify` (below).\n\nObtain the eventual outcome by polling\n`GET /api/v1/partner/users/{user_uuid}/verification-status` or consuming the\n`user.kyc.updated` webhook. The upload response does not include a verification session ID\nor `kyc_status`, because asynchronous state can change immediately after acceptance.\n","operationId":"uploadPartnerKYCDocument","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"Public UUID of the user","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document","document_type"],"properties":{"document":{"type":"string","format":"binary","description":"Document file (JPEG, PNG, GIF, or PDF, max 10MB)"},"document_type":{"$ref":"#/components/schemas/KycDocumentType"}}}},"application/json":{"schema":{"oneOf":[{"title":"Single URL Upload","description":"Upload one document by providing an HTTPS URL.","type":"object","required":["upload_method","document_type","url"],"properties":{"upload_method":{"type":"string","enum":["url_link"]},"document_type":{"$ref":"#/components/schemas/KycDocumentType"},"url":{"type":"string","format":"uri","description":"HTTPS URL of the image. 10MB max."}}},{"title":"Batch URL Upload","description":"Upload multiple documents in one call (up to 10).","type":"object","required":["upload_method","documents"],"properties":{"upload_method":{"type":"string","enum":["url_link"]},"documents":{"type":"array","maxItems":10,"items":{"type":"object","required":["document_type","url"],"properties":{"document_type":{"$ref":"#/components/schemas/KycDocumentType"},"url":{"type":"string","format":"uri"}}}}}}]}}}},"responses":{"200":{"description":"Documents accepted; verification starts asynchronously once all required documents are available","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"oneOf":[{"title":"Single document accepted","type":"object","required":["document_id","document_type","file_name","message"],"properties":{"document_id":{"type":"string","description":"Document identifier"},"document_type":{"type":"string"},"file_name":{"type":"string"},"message":{"type":"string","description":"Confirms that the document was accepted for processing."}}},{"title":"Batch documents accepted","type":"object","required":["uploaded","message"],"properties":{"uploaded":{"type":"array","items":{"type":"object","properties":{"document_type":{"type":"string"},"document_id":{"type":"string"},"file_name":{"type":"string"},"status":{"type":"string","enum":["uploaded"]}}}},"errors":{"type":"array","description":"Per-document failures, omitted when every document succeeds.","items":{"type":"object","properties":{"document_type":{"type":"string"},"error":{"type":"string"}}}},"message":{"type":"string"}}}]}}}}}},"400":{"description":"Bad Request - invalid file type, missing document, or user not ready for uploads"},"401":{"description":"Unauthorized"},"404":{"description":"User not found or no active KYC session"},"500":{"description":"Internal Server Error"}}}}}}
````

## Trigger KYC verification and check readiness

> Explicitly start KYC verification for a partner user on the \`direct\_data\` image flow, or check\
> what is still missing. Verification \*\*also\*\* starts automatically once an identity document +\
> selfie + KYC data are present (see the document upload endpoint) — this endpoint is an\
> explicit control and readiness check, not the only path. No request body.\
> \
> The response tells you the state:\
> \
> \- \*\*Ready, started:\*\* \`{ "ready": true, "status": "IN\_PROGRESS", "message": "Verification started." }\`.\
> &#x20; Idempotent — if a run is already in flight, the message is \`"Verification is already in progress."\`\
> &#x20; and no duplicate run is created.\
> \- \*\*Already verified:\*\* \`{ "ready": true, "status": "VERIFIED", "message": "User is already verified." }\`.\
> \- \*\*Not ready:\*\* \`{ "ready": false, "missing": \["identity\_document", "selfie"], "message": "..." }\`.\
> &#x20; The \`missing\` items are generic: \`identity\_document\` (any accepted ID type), \`selfie\`, \`kyc\_data\`.\
> \
> If the user has not submitted KYC with the \`direct\_data\` method yet, this returns \`400\` — submit\
> KYC via \`POST /api/v1/partner/users/{user\_uuid}/kyc-submissions\` first.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}}},"paths":{"/api/v1/partner/users/{user_uuid}/kyc/verify":{"post":{"tags":["User Management"],"summary":"Trigger KYC verification and check readiness","description":"Explicitly start KYC verification for a partner user on the `direct_data` image flow, or check\nwhat is still missing. Verification **also** starts automatically once an identity document +\nselfie + KYC data are present (see the document upload endpoint) — this endpoint is an\nexplicit control and readiness check, not the only path. No request body.\n\nThe response tells you the state:\n\n- **Ready, started:** `{ \"ready\": true, \"status\": \"IN_PROGRESS\", \"message\": \"Verification started.\" }`.\n  Idempotent — if a run is already in flight, the message is `\"Verification is already in progress.\"`\n  and no duplicate run is created.\n- **Already verified:** `{ \"ready\": true, \"status\": \"VERIFIED\", \"message\": \"User is already verified.\" }`.\n- **Not ready:** `{ \"ready\": false, \"missing\": [\"identity_document\", \"selfie\"], \"message\": \"...\" }`.\n  The `missing` items are generic: `identity_document` (any accepted ID type), `selfie`, `kyc_data`.\n\nIf the user has not submitted KYC with the `direct_data` method yet, this returns `400` — submit\nKYC via `POST /api/v1/partner/users/{user_uuid}/kyc-submissions` first.\n","operationId":"runPartnerKYCVerification","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"Public UUID of the user","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Readiness result. Either verification was triggered / is already running / the user is\nalready verified, or the user is not ready and `missing` lists what to provide.\n","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"ready":{"type":"boolean"},"status":{"type":"string","enum":["IN_PROGRESS","VERIFIED"],"description":"Present when `ready` is true."},"missing":{"type":"array","description":"Present when `ready` is false — the required items still to provide.","items":{"type":"string","enum":["identity_document","selfie","kyc_data"]}},"message":{"type":"string"}}}}}}}},"400":{"description":"Bad Request - the user has not submitted KYC with the direct_data method yet"},"401":{"description":"Unauthorized"},"404":{"description":"User not found"},"500":{"description":"Internal Server Error"}}}}}}
```

## Update KYC data for a partner user

> Update optional PII fields on existing KYC data. The user stays verified.\
> Only optional fields can be updated.\
> Required fields (first\_name, last\_name, country\_code) cannot be changed.\
> \
> For EUR/AUD/GBP offramp, provide address, city, and postal\_code here.\
> These will auto-populate into payment details for EUR/AUD/GBP payouts.\
> \
> \*\*Sender identity (consumer-to-consumer payout rails).\*\* Chinese mobile wallets\
> (Alipay, WeChat Pay) settle person to person: the receiving wallet must show the\
> paying customer as the remitter, not Unigox. \`POST /offramp/initiate\` returns\
> \`422 SENDER\_IDENTITY\_REQUIRED\` when the customer's record cannot name them, listing\
> the fields to send here in \`error.details.kyc\_fields\`. \`gender\`, \`nationality\`,\
> \`id\_issue\_country\` and \`source\_of\_funds\` exist for that flow, alongside \`dob\`,\
> \`phone\_number\`, \`id\_number\`, \`id\_type\` and the address fields the same rails need.\
> Send them once, then retry the order.\
> \
> The values are normalized before they are stored, and a value the rail would reject\
> is a \`400\` here rather than a failed payout later: \`gender\` accepts \`M\`/\`F\`\
> (\`MALE\`/\`FEMALE\` are folded in), \`nationality\` and \`id\_issue\_country\` take an ISO\
> 3166-1 alpha-2 code, and \`source\_of\_funds\` takes one of the listed slugs.\
> \
> Length is the exception, because the ceiling belongs to the payout rail and this record is\
> not tied to one: a value too long for a corridor is accepted here and comes back from that\
> corridor's \`initiate\` as a listed field, with the ceiling in \`error.details.field\_limits\`.\
> \
> The record belongs to the customer, not to a payout destination — never send another\
> person's details here to satisfy a payout.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}}},"paths":{"/api/v1/partner/users/{user_uuid}/kyc":{"patch":{"tags":["User Management"],"summary":"Update KYC data for a partner user","description":"Update optional PII fields on existing KYC data. The user stays verified.\nOnly optional fields can be updated.\nRequired fields (first_name, last_name, country_code) cannot be changed.\n\nFor EUR/AUD/GBP offramp, provide address, city, and postal_code here.\nThese will auto-populate into payment details for EUR/AUD/GBP payouts.\n\n**Sender identity (consumer-to-consumer payout rails).** Chinese mobile wallets\n(Alipay, WeChat Pay) settle person to person: the receiving wallet must show the\npaying customer as the remitter, not Unigox. `POST /offramp/initiate` returns\n`422 SENDER_IDENTITY_REQUIRED` when the customer's record cannot name them, listing\nthe fields to send here in `error.details.kyc_fields`. `gender`, `nationality`,\n`id_issue_country` and `source_of_funds` exist for that flow, alongside `dob`,\n`phone_number`, `id_number`, `id_type` and the address fields the same rails need.\nSend them once, then retry the order.\n\nThe values are normalized before they are stored, and a value the rail would reject\nis a `400` here rather than a failed payout later: `gender` accepts `M`/`F`\n(`MALE`/`FEMALE` are folded in), `nationality` and `id_issue_country` take an ISO\n3166-1 alpha-2 code, and `source_of_funds` takes one of the listed slugs.\n\nLength is the exception, because the ceiling belongs to the payout rail and this record is\nnot tied to one: a value too long for a corridor is accepted here and comes back from that\ncorridor's `initiate` as a listed field, with the ceiling in `error.details.field_limits`.\n\nThe record belongs to the customer, not to a payout destination — never send another\nperson's details here to satisfy a payout.\n","operationId":"updateKYC","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City"},"postal_code":{"type":"string"},"dob":{"type":"string","format":"date","description":"Date of birth (YYYY-MM-DD). Must be in the past and indicate an age of at least 18; a future, malformed, or under-18 date is rejected with HTTP 400."},"phone_number":{"type":"string","description":"E.164 format"},"middle_name":{"type":"string"},"id_number":{"type":"string","description":"Document number, as printed on the document named by `id_type`."},"id_type":{"type":"string","enum":["NATIONAL_ID","DRIVER_LICENSE","PASSPORT","RESIDENCE_PERMIT"]},"gender":{"type":"string","enum":["M","F"],"description":"Sender identity. As it appears on the identity document — payout rails match it against the document, so this is not a self-description field. `MALE`/`FEMALE` are accepted and normalized to `M`/`F`."},"nationality":{"type":"string","description":"Sender identity. Nationality as an ISO 3166-1 alpha-2 code."},"id_issue_country":{"type":"string","description":"Sender identity. Country that issued the document, ISO 3166-1 alpha-2. Often but not always the same as `nationality`."},"source_of_funds":{"type":"string","enum":["salary","business_income","savings","investment","gift","family_support","loan","sale_of_property","inheritance","other"],"description":"Sender identity. Where the money being sent comes from. Each payout rail maps this onto its own catalogue and refuses a payout it cannot map, so send the closest listed value rather than `other` when one applies."}}}}}},"responses":{"200":{"description":"KYC data updated successfully. `updated_fields` names only the fields that actually reached the record. A recognised field sent blank is a no-op rather than an error, so a patch whose recognised fields are all blank answers `200` with `updated_fields: []` and nothing is written — this endpoint does not clear a stored value.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"updated_fields":{"type":"array","items":{"type":"string"},"description":"Fields written by this patch. Empty when every recognised field in the body was blank."},"message":{"type":"string"}}}}}}}},"400":{"description":"Bad request — no valid fields, attempting to change a required field, or a value that fails validation. Body: `{ \"success\": false, \"data\": { \"error_key\": \"...\", \"message\": \"...\" } }`. DOB-related `error_key` values: `underage_not_allowed` (age under 18) and `invalid_date_of_birth` (malformed or future date). Sender-identity values: `invalid_gender`, `invalid_country_code` (`nationality` / `id_issue_country` is not an alpha-2 code) and `invalid_source_of_funds`. `invalid_field_value` means a value was sent as an object or an array where a string or a number is expected. `no_valid_kyc_fields` means the body carried no updatable field at all. Nothing is written when one field is rejected — fix it and resend the whole patch."},"401":{"description":"Unauthorized"},"404":{"description":"User not found"}}}}}}
```

## Verification status for a partner user

> Get the current verification status for a partner user. This endpoint returns the current status,\
> verification URL (if available), and other relevant information. Optionally, you can provide a\
> verification\_id to check a specific verification session.\
> \
> Status values:\
> \- \`NOT\_INITIATED\` — no verification started yet\
> \- \`PENDING\_DOCUMENTS\` — waiting for the customer to submit documents\
> \- \`IN\_PROGRESS\` — automated verification is underway (usually a couple of minutes)\
> \- \`UNDER\_REVIEW\` — under manual compliance review; the customer is being reviewed by our team\
> &#x20; and is NOT yet cleared. Unlike \`IN\_PROGRESS\` (automated, usually a couple of minutes), this can\
> &#x20; take up to 24 hours. Keep polling; treat as not cleared.\
> \- \`VERIFIED\` — verification passed; the customer is approved\
> \- \`FAILED\` — verification could not be completed due to an error\
> \- \`VERIFICATION\_REJECTED\` — verification completed with a rejection outcome\
> \
> Non-terminal states (\`NOT\_INITIATED\`, \`PENDING\_DOCUMENTS\`, \`IN\_PROGRESS\`, \`UNDER\_REVIEW\`) mean the\
> customer is not cleared yet — keep polling. A manual compliance review is now surfaced as the\
> friendly \`UNDER\_REVIEW\` (the internal review-state name is still never exposed) so you can tell a\
> long human review apart from a quick automated check and set the right expectation with your\
> customer.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"VerificationStatusResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["NOT_INITIATED","PENDING_DOCUMENTS","IN_PROGRESS","UNDER_REVIEW","VERIFIED","FAILED","VERIFICATION_REJECTED"],"description":"Current verification status.\n\n- `NOT_INITIATED` — no verification started\n- `PENDING_DOCUMENTS` — awaiting customer document submission\n- `IN_PROGRESS` — automated verification underway (usually a couple of minutes); treat as not cleared yet\n- `UNDER_REVIEW` — under manual compliance review; the customer is being reviewed by our team and is NOT yet cleared. Unlike `IN_PROGRESS` (automated, usually a couple of minutes), this can take up to 24 hours. Keep polling; treat as not cleared.\n- `VERIFIED` — approved\n- `FAILED` — terminal error\n- `VERIFICATION_REJECTED` — completed with rejection\n"},"verification_url":{"type":"string","format":"uri","nullable":true,"description":"Verification URL (for handoff method)"},"verification_seconds_left":{"type":"integer","nullable":true,"description":"Seconds remaining for verification session (if applicable)"},"rejection_reasons":{"type":"array","description":"Reasons for this customer's rejected verification, matching the KYC webhook. Empty for other statuses or when no reason is available.","items":{"type":"string"}},"provider_messages":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Status messages or rejection reasons"}}}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/verification-status":{"get":{"tags":["User Management"],"summary":"Verification status for a partner user","description":"Get the current verification status for a partner user. This endpoint returns the current status,\nverification URL (if available), and other relevant information. Optionally, you can provide a\nverification_id to check a specific verification session.\n\nStatus values:\n- `NOT_INITIATED` — no verification started yet\n- `PENDING_DOCUMENTS` — waiting for the customer to submit documents\n- `IN_PROGRESS` — automated verification is underway (usually a couple of minutes)\n- `UNDER_REVIEW` — under manual compliance review; the customer is being reviewed by our team\n  and is NOT yet cleared. Unlike `IN_PROGRESS` (automated, usually a couple of minutes), this can\n  take up to 24 hours. Keep polling; treat as not cleared.\n- `VERIFIED` — verification passed; the customer is approved\n- `FAILED` — verification could not be completed due to an error\n- `VERIFICATION_REJECTED` — verification completed with a rejection outcome\n\nNon-terminal states (`NOT_INITIATED`, `PENDING_DOCUMENTS`, `IN_PROGRESS`, `UNDER_REVIEW`) mean the\ncustomer is not cleared yet — keep polling. A manual compliance review is now surfaced as the\nfriendly `UNDER_REVIEW` (the internal review-state name is still never exposed) so you can tell a\nlong human review apart from a quick automated check and set the right expectation with your\ncustomer.\n","operationId":"getVerificationStatus","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}},{"name":"verification_id","in":"query","required":false,"description":"Optional verification session ID. If not provided, the latest verification session for the user will be checked.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved verification status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationStatusResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found"},"500":{"description":"Internal Server Error"}}}}}}
```

## Payment details for a partner user

> Retrieve all payment details (payment profiles) for a partner user. Returns all saved beneficiary details that can be used for offramp operations. Partners can only access their own users.

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"GetPaymentDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentProfile"},"description":"List of all payment profiles for the user"}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PaymentProfile":{"type":"object","properties":{"payment_details_id":{"type":"string","description":"Payment details ID. Use this value in offramp/onramp quote requests."},"rail":{"type":"string","description":"Payment rail identifier"},"currency":{"type":"string","description":"Fiat currency code"},"institution_name":{"type":"string","nullable":true,"description":"Institution (bank) name if applicable"},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","description":"Payment details (account number, VPA, IBAN, etc.)","additionalProperties":true}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/payment-details":{"get":{"tags":["User Management"],"summary":"Payment details for a partner user","description":"Retrieve all payment details (payment profiles) for a partner user. Returns all saved beneficiary details that can be used for offramp operations. Partners can only access their own users.","operationId":"getPaymentDetails","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successfully retrieved payment details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPaymentDetailsResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found"},"500":{"description":"Internal Server Error"}}}}}}
```

## Create payment details for a partner user

> Create payment details (beneficiary details) for a partner user. Used for offramp operations where crypto is converted to fiat and sent to the user's payment account. Partners can only access their own users.\
> \
> Payment details must belong to the same beneficiary represented by \`user\_uuid\`. Do not attach phone numbers, bank accounts, wallets, or other payout instruments for unrelated people to the same partner user. If you need to pay a different person, create a separate partner user for that beneficiary first.\
> \
> Institution handling:\
> \- for most rails, \`institution\_id\` must be provided from \`/api/v1/supported/institutions\`\
> \- partners may omit \`institution\_id\` only for the explicitly supported rails below\
> \
> Currently supported omission rails:\
> \- \`iban-sepa\`, \`nip-nigeria\`, \`faster-payments\` — resolve to the generic \`other-bank\` payment method\
> \- \`imps-neft-india\` — resolves to the generic \`imps-or-neft-transfer\` method; the bank comes from \`bank\_name\` + \`ifsc\_code\`\
> \- \`alipay-wallet\`, \`wechat-wallet\`, \`interac-e-transfer\` — resolve to the rail's own institution (\`alipay\`, \`wechat-pay\`, \`interac-e-transfers\`) and go through the same checks as if you had sent it<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"CreatePaymentDetailsRequest":{"description":"Conditional request schema for partner payment details. `institution_id` may be omitted for `iban-sepa`, `nip-nigeria`, and `imps-neft-india`.","oneOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestInstitutionOptional"},{"$ref":"#/components/schemas/CreatePaymentDetailsRequestInstitutionRequired"}]},"CreatePaymentDetailsRequestInstitutionOptional":{"allOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestBase"},{"type":"object","properties":{"rail":{"type":"string","enum":["iban-sepa","nip-nigeria","imps-neft-india"],"description":"Payment rail identifier for rails that support omission of `institution_id`"},"institution_id":{"type":"string","description":"Optional for `iban-sepa`, `nip-nigeria`, and `imps-neft-india`.\nFor `iban-sepa`/`nip-nigeria`, if omitted the backend assigns the generic `other-bank` payment method automatically.\nFor `imps-neft-india` it is ignored entirely (resolves to the generic `imps-or-neft-transfer` method); the bank is taken from `details.bank_name` + `details.ifsc_code`.\n"}}}]},"CreatePaymentDetailsRequestBase":{"type":"object","required":["currency","rail","details"],"properties":{"currency":{"type":"string","description":"ISO 3-letter fiat currency code (e.g., INR, EUR, USD)"},"rail":{"type":"string","description":"Payment rail identifier (e.g., \"upi-india\", \"iban-sepa\", \"imps-neft-india\")"},"details":{"type":"object","description":"Payment details object with fields specific to the payment network (e.g., account_number, vpa, iban, full_name)","additionalProperties":true},"country_code":{"type":"string","description":"Optional ISO 2-letter country code"}}},"CreatePaymentDetailsRequestInstitutionRequired":{"allOf":[{"$ref":"#/components/schemas/CreatePaymentDetailsRequestBase"},{"type":"object","required":["institution_id"],"properties":{"rail":{"type":"string","description":"Payment rail identifier for rails that require institution selection","not":{"enum":["iban-sepa","nip-nigeria","imps-neft-india"]}},"institution_id":{"type":"string","description":"Institution (payment method) identifier - our internal slug (e.g., \"wise\", \"hdfc-bank\", \"revolut\", \"uala\", \"banco-santander-argentina\").\nRequired for all rails except `iban-sepa`, `nip-nigeria`, and `imps-neft-india`.\nIf omitted for any other rail, the API returns a validation error.\nFor rails with multiple formats (e.g., CVU/CBU), the format is automatically determined based on the payment method type of this institution.\n"}}}]},"CreatePaymentDetailsResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentProfile"}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PaymentProfile":{"type":"object","properties":{"payment_details_id":{"type":"string","description":"Payment details ID. Use this value in offramp/onramp quote requests."},"rail":{"type":"string","description":"Payment rail identifier"},"currency":{"type":"string","description":"Fiat currency code"},"institution_name":{"type":"string","nullable":true,"description":"Institution (bank) name if applicable"},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","description":"Payment details (account number, VPA, IBAN, etc.)","additionalProperties":true}}},"ErrorResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["error_key"],"properties":{"error_key":{"type":"string","description":"Standardized error key for client error handling"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/payment-details":{"post":{"tags":["User Management"],"summary":"Create payment details for a partner user","description":"Create payment details (beneficiary details) for a partner user. Used for offramp operations where crypto is converted to fiat and sent to the user's payment account. Partners can only access their own users.\n\nPayment details must belong to the same beneficiary represented by `user_uuid`. Do not attach phone numbers, bank accounts, wallets, or other payout instruments for unrelated people to the same partner user. If you need to pay a different person, create a separate partner user for that beneficiary first.\n\nInstitution handling:\n- for most rails, `institution_id` must be provided from `/api/v1/supported/institutions`\n- partners may omit `institution_id` only for the explicitly supported rails below\n\nCurrently supported omission rails:\n- `iban-sepa`, `nip-nigeria`, `faster-payments` — resolve to the generic `other-bank` payment method\n- `imps-neft-india` — resolves to the generic `imps-or-neft-transfer` method; the bank comes from `bank_name` + `ifsc_code`\n- `alipay-wallet`, `wechat-wallet`, `interac-e-transfer` — resolve to the rail's own institution (`alipay`, `wechat-pay`, `interac-e-transfers`) and go through the same checks as if you had sent it\n","operationId":"createPaymentDetails","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentDetailsRequest"}}}},"responses":{"201":{"description":"Payment details created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentDetailsResponse"}}}},"400":{"description":"Bad Request - invalid payment details or unsupported combination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found"},"422":{"description":"Recipient details are incomplete or invalid for the payout corridor. The recipient fields you supply are validated against the provider's per-corridor requirements; if a required field is missing or malformed, the recipient is not created and the offending field names are listed in the error message. Fix the details and resubmit. Address fields auto-populated from KYC are not part of this check (a missing address does not block creation — see the KYC endpoints).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string","description":"Human-readable message naming the missing or invalid recipient fields."}}}}}},"500":{"description":"Internal Server Error"}}}}}}
```

## Get a single payment detail for a partner user

> Retrieve one payment detail (payment profile) by its \`payment\_details\_id\`, returning the same shape as one element of the list endpoint (\`rail\`, \`currency\`, \`institution\_name\`, \`institution\_id\`, \`details\`).\
> \
> Use this when you already hold a \`payment\_details\_id\` instead of listing every payment detail for the user — it stays fast on accounts with many saved payment details.\
> \
> Partners can only access their own users. A payment detail that belongs to a different user (or another partner) returns \`404\` rather than revealing that it exists.<br>

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"GetPaymentDetailResponse":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentProfile"}}}]},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"PaymentProfile":{"type":"object","properties":{"payment_details_id":{"type":"string","description":"Payment details ID. Use this value in offramp/onramp quote requests."},"rail":{"type":"string","description":"Payment rail identifier"},"currency":{"type":"string","description":"Fiat currency code"},"institution_name":{"type":"string","nullable":true,"description":"Institution (bank) name if applicable"},"institution_id":{"type":"string","nullable":true,"description":"Institution identifier (our internal slug)"},"details":{"type":"object","description":"Payment details (account number, VPA, IBAN, etc.)","additionalProperties":true}}},"ErrorResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["error_key"],"properties":{"error_key":{"type":"string","description":"Standardized error key for client error handling"}}}}}}},"paths":{"/api/v1/partner/users/{user_uuid}/payment-details/{payment_details_id}":{"get":{"tags":["User Management"],"summary":"Get a single payment detail for a partner user","description":"Retrieve one payment detail (payment profile) by its `payment_details_id`, returning the same shape as one element of the list endpoint (`rail`, `currency`, `institution_name`, `institution_id`, `details`).\n\nUse this when you already hold a `payment_details_id` instead of listing every payment detail for the user — it stays fast on accounts with many saved payment details.\n\nPartners can only access their own users. A payment detail that belongs to a different user (or another partner) returns `404` rather than revealing that it exists.\n","operationId":"getPaymentDetailById","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}},{"name":"payment_details_id","in":"path","required":true,"description":"The payment_details_id returned when creating or listing payment details.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved the payment detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPaymentDetailResponse"}}}},"400":{"description":"Bad Request - malformed payment_details_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found, or payment detail not found / not owned by this user"},"500":{"description":"Internal Server Error"}}}}}}
```

## Delete payment details for a partner user

> Delete a specific payment details (payment profile) for a partner user by its ID. Partners can only access their own users.

```json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"User Management","description":"Create and manage your customers, put them through KYC, hold their payout details — and issue\nthe fiat accounts they are paid into.\n\nAll of it hangs off one customer. `POST /api/v1/partner/users` creates them and answers with\nthe `user_uuid` every route below takes in its path; KYC verifies them; and an account is\nopened for that same person. There is no second identity to register and no separate customer\nrecord for banking — the person Unigox verified is the person the account belongs to.\n\n**Customer-owned wallets and crypto deposits**\n\n1. Ask Unigox to enable external-wallet customers for your partner account.\n2. Create the customer with `wallet_type: external_wallet`. Omitting it creates a\n   `partner_wallet` customer. The type is fixed at creation; use the same type when\n   repeating a request for an existing `user_ref`.\n3. Request `POST /api/v1/partner/users/{user_uuid}/wallet/challenge` for the customer's\n   EVM address. Have that wallet sign the returned `message` unchanged with `personal_sign`\n   or its equivalent `signMessage` operation.\n4. Submit `address`, `message` and `signature` to `POST /api/v1/partner/users/{user_uuid}/wallet`.\n   `GET` on that path returns the link status and XAI balances.\n5. Allocate deposit addresses and check their monitoring status before accepting payments.\n   Supported deposits are credited to the linked wallet on UNIGOX, on XAI (chain ID 660279).\n   Register your partner webhook to receive `wallet.deposit.received` after a bridge credit.\n\nEnabling external-wallet customers controls new customer creation. Existing external-wallet\ncustomers can still link their wallet, read it and deposit if that permission is later disabled.\nThese routes use `X-API-Key` and your customer UUID. Wallet-signed Bridge memo addresses use\nthe separate Bridge payment API; the partner deposit-address routes do not attach memos.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}}},"paths":{"/api/v1/partner/users/{user_uuid}/payment-details/{payment_details_id}":{"delete":{"tags":["User Management"],"summary":"Delete payment details for a partner user","description":"Delete a specific payment details (payment profile) for a partner user by its ID. Partners can only access their own users.","operationId":"deletePaymentDetails","parameters":[{"name":"user_uuid","in":"path","required":true,"description":"The user_uuid returned by POST /partner/users. Partners can only access their own users.","schema":{"type":"string","format":"uuid"}},{"name":"payment_details_id","in":"path","required":true,"description":"The payment_details_id returned when creating payment details.","schema":{"type":"string"}}],"responses":{"200":{"description":"Payment details deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"User not found or payment details not found"},"409":{"description":"Conflict - payment details linked to active offers"},"500":{"description":"Internal Server Error"}}}}}}
```
