Transfers API

The Transfers API allows you to transfer funds between two customers on the Sznd platform.

Overview

Transfers enable peer-to-peer money transfers between users on the platform. You can transfer funds:

  • Same Currency: Direct transfer between wallets of the same currency

Two Methods for Transfers

Method 1: Transfer via Quotes (Recommended)

Use the Quotes API with quote_type: TRANSFER to create transfers. This method includes fee calculations and provides better control over the transfer process.

Method 2: Direct Transfer

Use the direct transfer endpoint for same-currency transfers between wallets. This is simpler but only works for transfers within the same currency.

Method 1: Transfer via Quotes

Create a transfer quote and accept it to complete the transfer. This method provides detailed fee information.

Step 1: Look Up Recipient by User Tag

Before creating a transfer, you may want to verify the recipient's user tag.

Endpoint: GET /api/v1/client/users/by-tag

Authentication: Required (HMAC - Business API Key)

Include your API key and signature in the request headers:

http
x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>

Query Parameters:

  • tag (string, required) - User tag to look up (4-20 alphanumeric characters)

Success Response (200 OK):

json
{  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "first_name": "Jane",  "last_name": "Doe",  "email": "jane.doe@example.com",  "user_tag": "janedoe123",  "type_id": 1,  "type_name": "Individual",  "role_id": 1,  "role_name": "CUSTOMER",  "status": "ACTIVE"}

Step 2: Create Transfer Quote

Endpoint: POST /api/v1/client/quotes

Authentication: Required (HMAC - Business API Key)

Include your API key and signature in the request headers:

http
x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>

Request Body:

json
{  "source_currency": "USD",  "target_currency": "USD",  "source_amount": "100.00",  "quote_type": "TRANSFER",  "user_tag": "janedoe123",  "fee_config_id": "2fbdb973-39fd-4217-aa9b-e7b8ccc9e457",  "tz": "UTC",  "narration": "Payment for services"}

Required Parameters:

  • source_currency (string) - Currency to transfer from
  • target_currency (string) - Currency to transfer to
  • source_amount (string) - Amount to transfer in source currency
  • quote_type (string) - Must be TRANSFER
  • user_tag (string) - User tag of the recipient
  • fee_config_id (string, UUID) - Fee configuration ID
  • tz (string) - Timezone (IANA format)

Optional Parameters:

  • narration (string) - Description for the transfer

Success Response (201 Created):

json
{  "quote_id": "123e4567-e89b-12d3-a456-426614174000",  "source": {    "currency": "USD",    "amount": "100.00"  },  "target": {    "currency": "USD",    "amount": "100.00"  },  "exchange_rate": "1.00",  "fees": {    "processing_fee": "2.00",    "deposit_fee": "0.00",    "payout_fee": "0.00",    "total_fees": "2.00",    "fee_currency": "USD"  },  "total_payable": "100.00",  "valid_until": "2025-03-09T01:40:53Z",  "quote_status": "CREATED",  "type": "TRANSFER"}

Step 3: Accept Transfer Quote

Endpoint: POST /api/v1/client/quotes/{id}/accept

Authentication: Required (HMAC - Business API Key)

Include your API key and signature in the request headers:

http
x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>

Path Parameters:

  • id (UUID) - Quote ID from Step 2

Success Response (200 OK):

json
{  "quote_id": "123e4567-e89b-12d3-a456-426614174000",  "transaction_id": "223e4567-e89b-12d3-a456-426614174001",  "transaction_reference": "TRX-20240501-XYZ123",  "total_payable": "102.00",  "timeline": {    "created_at": "2024-03-09T01:10:53Z",    "valid_until": "2024-03-09T01:40:53Z"  }}

Example: Complete Transfer Flow

Step 1: Verify recipient exists

bash
curl -X GET "https://api.sznd.app/api/v1/client/users/by-tag?tag=janedoe123" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -H "Content-Type: application/json"

Step 2: Create transfer quote

bash
curl -X POST "https://api.sznd.app/api/v1/client/quotes" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -H "Content-Type: application/json" \  -d '{    "source_currency": "USD",    "target_currency": "NGN",    "source_amount": "100.00",    "quote_type": "TRANSFER",    "user_tag": "janedoe123",    "fee_config_id": "2fbdb973-39fd-4217-aa9b-e7b8ccc9e457",    "tz": "UTC",    "narration": "Payment for services"  }'

Step 3: Accept the quote

bash
curl -X POST "https://api.sznd.app/api/v1/client/quotes/{quote_id}/accept" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -H "Content-Type: application/json"

Example: HTTP Requests

Step 1: Look up user by tag

http
GET /api/v1/client/users/by-tag?tag=janedoe123 HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json

Step 2: Create transfer quote

http
POST /api/v1/client/quotes HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json
{  "source_currency": "USD",  "target_currency": "NGN",  "source_amount": "100.00",  "quote_type": "TRANSFER",  "user_tag": "janedoe123",  "fee_config_id": "2fbdb973-39fd-4217-aa9b-e7b8ccc9e457",  "tz": "UTC",  "narration": "Payment for services"}

Step 3: Accept quote

http
POST /api/v1/client/quotes/{quote_id}/accept HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json

Method 2: Direct Transfer (Same Currency Only)

For same-currency transfers, you can use the direct transfer endpoint. This is simpler but only works when both wallets use the same currency.

Endpoint

Client API Endpoint: POST /api/v1/client/transactions/transfer

Note: This method is for same-currency transfers only.

Authentication

This endpoint requires HMAC authentication (Business API Key). Include your API key and signature in the request headers:

http
x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>

Note: For HMAC authentication details, see the Authentication guide.

Request Body

json
{  "source_wallet_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",  "target_wallet_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg",  "amount": "100.00",  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"}

Parameters:

  • source_wallet_id (UUID, required) - Your wallet ID (must belong to authenticated user)
  • target_wallet_id (UUID, required) - Recipient's wallet ID
  • amount (string, required) - Amount to transfer (decimal string)
  • idempotency_key (UUID, required) - Unique key to prevent duplicate transfers

Important Notes

  • Same Currency Required: Both wallets must use the same currency
  • Wallet Ownership: Source wallet must belong to the authenticated user
  • Idempotency: Using the same idempotency_key will return the existing transaction instead of creating a duplicate

Success Response (201 Created)

json
{  "id": "123e4567-e89b-12d3-a456-426614174000",  "user_id": "111e4567-e89b-12d3-a456-426614174000",  "transaction_type": "TRANSFER",  "status": "PENDING",  "source_wallet_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",  "target_wallet_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg",  "source_amount": "100.00",  "source_currency": "USD",  "target_amount": "100.00",  "target_currency": "USD",  "created_at": "2024-05-01T14:00:00Z",  "updated_at": "2024-05-01T14:00:00Z"}

Error Responses

Status CodeDescription
400Invalid request, insufficient funds, or currency mismatch
401Unauthorized - Invalid or missing API key or signature
403Forbidden - Source wallet does not belong to authenticated customer
404Wallet not found
500Internal server error

Example: Direct Transfer

bash
curl -X POST "https://api.sznd.app/api/v1/client/transactions/transfer" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -H "Content-Type: application/json" \  -d '{    "source_wallet_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",    "target_wallet_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg",    "amount": "100.00",    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"  }'

Example: HTTP Request

http
POST /api/v1/client/transactions/transfer HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json
{  "source_wallet_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",  "target_wallet_id": "b2c3d4e5-f6a7-8901-2345-678901bcdefg",  "amount": "100.00",  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"}

User Tags

User tags are unique identifiers that allow users to receive transfers without exposing their wallet IDs or email addresses. Each user can set a custom user tag.

Set User Tag

Endpoint: PUT /api/v1/client/users/tag

Authentication: Required (HMAC - Business API Key)

Include your API key and signature in the request headers:

http
x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>

Request Body:

json
{  "user_tag": "myusertag123"}

Requirements:

  • 4-20 alphanumeric characters
  • Must be unique across the platform
  • Pattern: ^[a-zA-Z0-9]+$

Success Response (200 OK):

json
{  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "user_tag": "myusertag123",  "message": "User tag updated successfully"}

Look Up User by Tag

Endpoint: GET /api/v1/client/users/by-tag?tag={user_tag}

Authentication: Required (HMAC - Business API Key)

Include your API key and signature in the request headers:

http
x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>

Query Parameters:

  • tag (string, required) - User tag to look up

Success Response (200 OK):

json
{  "user_id": "123e4567-e89b-12d3-a456-426614174000",  "first_name": "Jane",  "last_name": "Doe",  "email": "jane.doe@example.com",  "user_tag": "janedoe123",  "type_name": "Individual",  "status": "ACTIVE"}

Transfer Requirements

Prerequisites

  1. Source User must have:

    • Active account
    • Wallet in source currency
    • Sufficient available balance

  2. Recipient User must have:

    • Active account
    • Wallet in target currency (will be created automatically if needed)
    • Valid user tag (for quote-based transfers)

  3. Both users must be:

    • KYC verified (if required for the currency/amount)
    • In good standing

Transfer Limits

Transfer limits may apply based on:

  • User verification status
  • Currency-specific limits
  • Daily/monthly transaction limits

Check the Exchange Rates API to see applicable limits for a transfer.

Currency Conversion

Exchange rate is locked when the quote is created and fees are calculated and included in the quote.

Transfer Status

Transfers go through the following statuses:

  • PENDING - Transfer is pending processing
  • PROCESSING - Transfer is being processed
  • COMPLETED - Transfer completed successfully
  • FAILED - Transfer failed
  • CANCELLED - Transfer was cancelled

Check Transfer Status

bash
curl -X GET "https://api.sznd.app/api/v1/client/transactions/v2/{transaction_id}" \  -H "x-api-key: your_api_key_here" \  -H "x-timestamp: 2025-01-30T12:20:15Z" \  -H "x-signature: generated_signature_here" \  -H "Content-Type: application/json"

Example: HTTP Request

http
GET /api/v1/client/transactions/v2/{transaction_id} HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json

Error Handling

Common Errors

Status CodeErrorDescription
400Invalid requestMissing required fields, invalid amounts, or validation errors
401UnauthorizedInvalid or missing API key or signature
403ForbiddenSource wallet doesn't belong to user, or transfer to self
404Not foundRecipient user tag not found, or wallet not found
422Limit violationTransfer amount exceeds limits

Error Response Format

json
{  "error": "Target user not found",  "message": "No user found with the provided user tag"}

Best Practices

  1. Verify Recipient First - Always look up the user tag before creating a transfer to confirm the recipient
  2. Use Idempotency Keys - Always include unique idempotency keys to prevent duplicate transfers
  3. Check Balance - Verify sufficient balance before creating transfers
  4. Handle Errors - Implement proper error handling for failed transfers
  5. Monitor Status - Track transfer status and notify users of completion
  6. Use Quotes - Use the quote method when you only have the recipient's tag
  7. Store Transaction References - Save transaction references for reconciliation and support

Use Cases

  1. P2P Payments - Enable users to send money to each other
  2. Marketplace Payments - Process payments between buyers and sellers
  3. Gig Economy - Pay freelancers and contractors
  4. Remittances - Send money to family and friends
  5. Business Payments - Transfer funds between business accounts

Webhook Integration

Set up webhooks to receive real-time notifications when transfers complete or fail. This allows you to:

  • Update your system automatically when transfers complete
  • Handle failed transfers and notify users
  • Reconcile transfers in your database

See the Webhooks documentation for more information.

Next Steps