> ## Documentation Index > Fetch the complete documentation index at: https://docs.sakawave.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a transfer destination > Resolves where money is going, and proves it can get there. `type` selects one of three shapes: your own account, a Sakawave tag, or an external account described inline. The result expires after 24 hours and can be spent once. ## Three shapes, one endpoint | `type` | Send | Resolves to | | - | - | - | | `own_account` | `accountId`, `currency` | One of your own accounts. | | `sakawave_tag` | `tag` | Any Sakawave account, by its public handle. | | `external` | `routeId`, `currency`, `accountName`, plus the route’s routing fields | A bank or mobile-money account elsewhere. | ## Every "not found" looks the same For `own_account` and `sakawave_tag`, one code covers every reason the target cannot receive: it does not exist, it is not active, it cannot be credited, its currency differs, or — for your own accounts — it is a customer wallet or is not yet `transferReady`. ```json { "statusCode": 404, "message": "Destination account not found.", "code": "destination_account_not_found" } ``` That is deliberate: a caller must not be able to probe which accounts exist. When you meet it against your own account, read the account and check `status`, `canCredit`, `currency`, and `transferReady` yourself. You cannot use `own_account` to pay a customer wallet. Wallets are excluded from that shape; pay them by `sakawave_tag`. ## The counterparty profile On an external route that settles through the international provider, four fields are required by the payout rail even though the parser treats them as optional: `recipientRelationship`, `recipientEmail`, `recipientAddressLine1`, and `recipientCity`, plus a resolved `country`. Omitting them fails with `422 recipient_profile_incomplete`, listing each one. Domestic NGN routes do not ask for them. ## Verification Where the route supports it, Sakawave looks the account up with the provider and **replaces `accountName` with the verified name**. The `displayName` you get back is therefore the name the bank holds, not the name you sent — show it to the payer before they confirm. ## Error codes | Status | `code` | Cause | | - | - | - | | `400` | `validation_failed` | A field failed validation, or a field this shape does not accept was sent. | | `404` | `destination_account_not_found` | The own-account or tag target cannot receive. See above. | | `404` | `transfer_route_not_found` | No active route with that id delivers to that currency. | | `409` | `currency_capability_unavailable` | The destination currency is closed for this kind of transfer. | | `409` | `route_country_mismatch` | The route does not serve the country you named. | | `409` | `destination_country_required` | A bank-transfer route needs a destination country. | | `409` | `destination_field_required` | A field the route requires was not sent. The field name is in `field`. | | `409` | `transfer_provider_unavailable` | No provider is currently bound to the route. | | `422` | `recipient_profile_incomplete` | One or more counterparty fields are missing; each is listed in `errors`. | | `503` | `destination_provider_unavailable` | The route is bound to a provider that cannot serve it. | | `503` | `provider_unavailable` | The provider could not be reached. Retry shortly. | | `401` | `INVALID_API_KEY` | The key is missing, invalid, inactive, expired, from the other environment, or blocked by its IP allowlist. | | `429` | `api_key_rate_limit_exceeded` | The per-minute limit for this key was exceeded. | ## OpenAPI ````yaml /openapi.json post /v1/transfer-destinations openapi: 3.1.0 info: title: Sakawave Business API version: 1.0.0-draft summary: >- Accounts, transfers, FX quotes, and transaction reconciliation for Sakawave businesses. description: >- Generated from the public NestJS controllers and their Zod request schemas. Public URLs and policy statements remain draft until the Phase 1 contract checklist is approved. contact: name: Sakawave API Support email: api-support@sakawave.example servers: - url: https://sandbox-api.sakawave.example description: Sandbox (default) - url: https://api.sakawave.example description: Live security: - bearerAuth: [] tags: - name: Bill payments description: Browse the biller catalog, validate a customer, and pay a bill. - name: Cards description: Issue, fund, and control USD virtual and disposable cards. - name: eSIM description: >- Sell mobile data abroad: browse the catalog, buy an eSIM, and manage it once installed. - name: Currencies and countries description: >- Reference data: what may be held, what may be sent where, and which jurisdictions are served. - name: Customers description: Create and manage customers of your business. - name: Accounts description: >- Open business and customer accounts, and issue the destinations that fund them. - name: Transfer destinations description: Resolve temporary destinations and saved recipients. - name: FX quotes description: Create and retrieve time-limited cross-currency quotes. - name: Transfers description: Preview, create, and monitor transfers. - name: Transactions description: Read ledger entries for reconciliation. paths: /v1/transfer-destinations: post: tags: - Transfer destinations summary: Create a transfer destination description: >- Resolves where money is going, and proves it can get there. `type` selects one of three shapes: your own account, a Sakawave tag, or an external account described inline. The result expires after 24 hours and can be spent once. operationId: createTransferDestination requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDestinationRequest' example: type: external routeId: 01K2Z3AB4M5N6P7Q8RSTVWXYZA currency: KES country: KE accountName: Ada Okafor recipientType: individual recipientRelationship: vendor recipientEmail: ada@example.com recipientAddressLine1: 14 Marina Road recipientCity: Nairobi bankCode: '001' accountNumber: '0123456789' saveRecipient: false responses: '201': description: Successful response. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/DestinationResponse' example: id: 01K2Z3AB4F5G6H7J8KMNPQRSTV type: own_account currency: NGN displayName: Treasury NGN routeId: null recipientId: null institutionName: null accountNumberLast4: null expiresAt: '2026-08-15T09:05:00.000Z' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/AuthenticationError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/ConflictError' '422': $ref: '#/components/responses/UnprocessableError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ProviderUnavailableError' security: - bearerAuth: [] components: schemas: CreateDestinationRequest: oneOf: - $ref: '#/components/schemas/OwnDestinationRequest' - $ref: '#/components/schemas/TagDestinationRequest' - $ref: '#/components/schemas/ExternalDestinationRequest' discriminator: propertyName: type mapping: own_account: '#/components/schemas/OwnDestinationRequest' sakawave_tag: '#/components/schemas/TagDestinationRequest' external: '#/components/schemas/ExternalDestinationRequest' DestinationResponse: type: object additionalProperties: false properties: id: $ref: '#/components/schemas/Ulid' description: Send this as destinationId when previewing or creating a transfer. type: type: string enum: - own_account - sakawave_tag - external currency: $ref: '#/components/schemas/DestinationCurrency' displayName: type: string description: >- The verified account name for an external destination, the account name for your own, or the resolved holder for a tag. routeId: anyOf: - $ref: '#/components/schemas/Ulid' description: The payout route, for external destinations. - type: 'null' recipientId: anyOf: - $ref: '#/components/schemas/Ulid' description: The saved recipient this was built from, when it was. - type: 'null' institutionName: anyOf: - type: string - type: 'null' accountNumberLast4: anyOf: - type: string minLength: 4 maxLength: 4 description: The only part of the destination account number ever returned. - type: 'null' expiresAt: $ref: '#/components/schemas/IsoTimestamp' required: - id - type - currency - displayName - routeId - recipientId - institutionName - accountNumberLast4 - expiresAt OwnDestinationRequest: type: object additionalProperties: false properties: type: const: own_account accountId: $ref: '#/components/schemas/Ulid' currency: $ref: '#/components/schemas/Currency' required: - type - accountId - currency TagDestinationRequest: type: object additionalProperties: false properties: type: const: sakawave_tag tag: type: string minLength: 3 maxLength: 32 required: - type - tag ExternalDestinationRequest: type: object additionalProperties: false properties: type: const: external routeId: $ref: '#/components/schemas/Ulid' description: From GET /v1/transfer-corridors or GET /v1/currencies/{code}/routes. currency: $ref: '#/components/schemas/DestinationCurrency' country: type: string minLength: 2 maxLength: 2 description: >- Required for a bank-transfer route that is not already scoped to a country. accountName: type: string minLength: 2 maxLength: 200 description: >- Replaced by the verified name when the route supports account verification. recipientType: type: string enum: - individual - business default: individual recipientRelationship: type: string minLength: 2 maxLength: 80 description: Required by the payout provider on non-NGN routes. recipientEmail: type: string format: email description: Required by the payout provider on non-NGN routes. recipientAddressLine1: type: string minLength: 2 maxLength: 200 description: Required by the payout provider on non-NGN routes. recipientCity: type: string minLength: 2 maxLength: 100 description: Required by the payout provider on non-NGN routes. recipientStateOrProvince: type: string maxLength: 100 recipientPostalCode: type: string maxLength: 24 institutionName: type: string minLength: 2 maxLength: 160 accountNumber: type: string minLength: 3 maxLength: 80 writeOnly: true x-mint: pre: - sensitive routingNumber: type: string maxLength: 40 writeOnly: true sortCode: type: string maxLength: 40 writeOnly: true iban: type: string maxLength: 80 writeOnly: true x-mint: pre: - sensitive swiftBic: type: string maxLength: 40 bankCode: type: string maxLength: 40 branchCode: type: string maxLength: 40 bankInstitutionNumber: type: string maxLength: 40 transitNumber: type: string maxLength: 40 accountType: type: string maxLength: 40 saveRecipient: type: boolean default: false description: Also save this as a reusable recipient. phoneNumber: type: string maxLength: 24 bsb: type: string maxLength: 12 walletAddress: type: string minLength: 32 maxLength: 64 description: >- The address a `stablecoin-transfer` route pays. Must be an address on the route’s chain. Screened against sanctions lists before it is accepted, and again when it is paid. required: - type - routeId - currency - accountName Ulid: type: string minLength: 26 maxLength: 26 pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$ example: 01K2Z3AB4C5D6E7F8G9HJKMNPQ description: A 26-character ULID. DestinationCurrency: type: string enum: - NGN - USD - GBP - EUR - GHS - ZAR - UGX - CAD - MXN - AED - AUD - SGD - HKD - KES - TZS - BRL - CNY - XAF - PHP - USDC IsoTimestamp: type: string format: date-time example: '2026-08-14T09:00:00.000Z' RequestError: anyOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/Error' description: >- Either a field-level validation failure carrying an errors array, or a rule the request broke, identified by code. Error: type: object additionalProperties: true properties: statusCode: type: integer message: type: string description: >- A sentence suitable for a log or a support conversation, not for a user interface. code: type: string description: >- The stable machine-readable reason. Branch on this, never on the message. required: - message - code description: >- An error body. Individual errors may add context fields alongside these three. UnprocessableError: type: object additionalProperties: true properties: statusCode: const: 422 message: type: string code: type: string enum: - payment_detail_invalid - recipient_profile_incomplete description: >- Present on validation refusals. Absent on tier denials, which carry `reason` instead. reason: type: string enum: - daily_outflow_limit_exceeded - wallet_cap_exceeded description: Present on tier denials. errors: type: array items: $ref: '#/components/schemas/ValidationFailure' currency: $ref: '#/components/schemas/AssetCode' currentTier: type: integer enum: - 1 - 2 - 3 limit: type: integer description: The allowance, in minor units. spentToday: type: integer description: Already spent inside the current daily window, in minor units. remaining: type: integer description: What is left of the allowance, in minor units. attempted: type: integer description: What this request asked for, in minor units. required: - statusCode - message description: >- A refusal the caller can act on. Individual reasons add context fields alongside these. RateLimitError: type: object additionalProperties: false properties: statusCode: const: 429 message: type: string code: const: api_key_rate_limit_exceeded retryAfterSeconds: type: integer minimum: 1 required: - statusCode - message - code - retryAfterSeconds Currency: type: string enum: - NGN - USD - GBP - EUR - GHS - ZAR - UGX - CAD - MXN - AED ValidationError: type: object additionalProperties: false properties: statusCode: const: 400 message: type: string description: The single failure, or a count when more than one field failed. code: const: validation_failed errors: type: array items: $ref: '#/components/schemas/ValidationFailure' required: - statusCode - message - code - errors ValidationFailure: type: object additionalProperties: false properties: message: type: string field: type: string code: type: string path: type: array items: anyOf: - type: string - type: integer required: - message - field - code - path AssetCode: type: string enum: - NGN - USD - GBP - EUR - GHS - ZAR - UGX - CAD - MXN - AED - BTC - ETH - USDT - USDC responses: ValidationError: description: >- The request was rejected before it was acted on. Field failures list every failing field. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/RequestError' example: statusCode: 400 message: Must be a valid identifier. code: validation_failed errors: - message: Must be a valid identifier. field: accountId code: custom path: - accountId AuthenticationError: description: >- The API key is missing, invalid, inactive, expired, for another environment, or blocked by its IP allowlist. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 401 code: INVALID_API_KEY message: Invalid or inactive API credentials. NotFoundError: description: The requested resource was not found for this business. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 404 code: resource_not_found message: Resource not found. ConflictError: description: The request conflicts with the current resource state. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 409 code: resource_conflict message: The request conflicts with the current resource state. UnprocessableError: description: The request was well formed but cannot be acted on. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/UnprocessableError' example: statusCode: 422 message: Payment detail validation failed. code: payment_detail_invalid errors: - message: Account number is required. field: accountNumber code: required path: - fields - accountNumber RateLimitError: description: The API key rate limit was exceeded. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/RateLimitError' example: statusCode: 429 message: Too many API requests. Try again later. code: api_key_rate_limit_exceeded retryAfterSeconds: 17 ServerError: description: An unexpected server error occurred. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 500 code: internal_server_error message: An unexpected error occurred. ProviderUnavailableError: description: >- A payment provider could not be reached. The request had no effect; retry shortly. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 503 code: provider_unavailable message: We could not issue an account number just now. Try again shortly. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Sakawave API key description: >- A secret API key, sent as `Authorization: Bearer sk_test_…` in sandbox or `Bearer sk_live_…` in live. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.