Deposit API

The Paybin Deposit API allows you to create unique deposit addresses for your customers to send cryptocurrencies. Each deposit address is tied to a specific transaction and can be used to track payments securely.

Create Deposit Address

This endpoint generates a new deposit address for a specific cryptocurrency and network. The address can be used by your customers to send payments.

  • Name
    PublicKey
    Type
    string
    Description

    Your Paybin Public Key, used to authenticate the request.

  • Name
    Symbol
    Type
    string
    Description

    The cryptocurrency symbol (e.g., ETH, BTC, USDT) for which to create a deposit address.

    See all Symbols
  • Name
    Label
    Type
    string
    Description

    A user-friendly label for the deposit address, helping you identify the purpose of the deposit.

  • Name
    ReferenceId
    Type
    string
    Description

    A unique identifier for the deposit request, used for tracking and reconciliation.

  • Name
    CallbackUrl
    Type
    string
    Description

    URL where Paybin will send webhook notifications when deposits are received.

  • Name
    Amount
    Type
    decimal
    Description

    Optional: The expected amount for this deposit. Used for price calculation and validation.

  • Name
    Currency
    Type
    string
    Description

    Optional: The fiat currency for price calculation (USD, EUR, etc.).

  • Name
    RedirectUrl
    Type
    string
    Description

    Optional: URL to redirect users after successful deposit.

  • Name
    CancelUrl
    Type
    string
    Description

    Optional: URL to redirect users if they cancel the deposit.

  • Name
    Hash
    Type
    string
    Description

    A unique hash generated for the request, serving as an additional layer of security.

    How to create hash

    const hashString = PublicKey + Symbol + Label + ReferenceId + CallbackUrl;
const hash = CryptoJS.MD5(hashString + secretKey).toString();

Create Deposit Address

curl --location 'https://sandbox.paybin.io/v1/deposit/address/create' \
--header 'X-Api-Key: {secretKey}' \
--header 'Content-Type: application/json' \
--data '{
  "PublicKey": "{publicKey}",
  "Symbol": "ETH",
  "Label": "Payment for Order #123",
  "ReferenceId": "ORDER_123",
  "CallbackUrl": "https://your-domain.com/webhook/paybin",
  "Amount": 0.1,
  "Currency": "USD",
  "Hash": "{HASH}"
}'

Response

{
  "apiVersion": "1.0.0.0",
  "data": {
    "wallet": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "referenceGuid": "550e8400-e29b-41d4-a716-446655440001",
    "symbol": "ETH",
    "network": "Ethereum Mainnet",
    "price": {
      "usd": 2500.00,
      "eur": 2200.00,
      "gbp": 1900.00,
      "try": 75000.00,
      "jpy": 350000.00
    },
    "supportedNetworks": [
      "Ethereum Mainnet",
      "Optimism Mainnet"
    ],
    "contractTypes": [
      "ERC-20"
    ],
    "minAmounts": [
      {
        "currency": "USD",
        "amount": 10.00
      },
      {
        "currency": "EUR",
        "amount": 8.50
      }
    ],
    "information": "Send exactly 0.1 ETH to this address"
  },
  "code": 200,
  "message": "OK"
}

Exception

{
  "apiVersion": "1.0.0.0",
  "data": null,
  "code": 400,
  "message": "Z503"
}

Get Address

This endpoint retrieves an existing deposit address for a specific member and cryptocurrency.

  • Name
    PublicKey
    Type
    string
    Description

    Your Paybin Public Key, used to authenticate the request.

  • Name
    MemberId
    Type
    string
    Description

    The unique identifier for the member requesting the address.

  • Name
    Symbol
    Type
    string
    Description

    The cryptocurrency symbol for which to retrieve the address.

  • Name
    Label
    Type
    string
    Description

    Optional: A label to identify the purpose of this address.

  • Name
    NetworkId
    Type
    long
    Description

    Optional: The specific network ID for multi-network cryptocurrencies.

Get Address

curl --location 'https://sandbox.paybin.io/v1/deposit/address/get' \
--header 'X-Api-Key: {secretKey}' \
--header 'Content-Type: application/json' \
--data '{
  "PublicKey": "{publicKey}",
  "MemberId": "MEMBER_001",
  "Symbol": "ETH",
  "Label": "My ETH Wallet",
  "NetworkId": 1
}'

Response

{
  "apiVersion": "1.0.0.0",
  "data": {
    "memberWalletId": 12345,
    "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "symbol": "ETH",
    "networkId": 1,
    "network": "Ethereum Mainnet",
    "referenceGuid": "550e8400-e29b-41d4-a716-446655440001",
    "isContract": false,
    "supportedNetworks": [
      "Ethereum Mainnet",
      "Optimism Mainnet"
    ],
    "contractTypes": [],
    "information": "This is your personal ETH wallet address"
  },
  "code": 200,
  "message": "OK"
}

Supported Networks

Paybin supports multiple blockchain networks for each cryptocurrency. Here are the supported networks and their corresponding symbols:

AssetNetworks and Symbols
BTCBitcoin Mainnet (BTC)
LTCLitecoin Mainnet (LTC)
ETHEthereum Mainnet (ETH), Optimism Mainnet (OPT-ETH)
USDTEthereum Mainnet (USDT), Binance Smartchain (BSC-USD), Optimism Mainnet (OPT-USD)
USDCEthereum Mainnet (ETH-USDC), Binance Smartchain (BSC-USDC)
BNBBinance Smartchain (BNB)

Network IDs

NetworkNetwork IDDescription
Bitcoin Mainnet1Bitcoin blockchain
Litecoin Mainnet2Litecoin blockchain
Ethereum Mainnet3Ethereum blockchain
Binance Smartchain4BSC blockchain
Optimism Mainnet5Optimism blockchain

Callback Notifications

When a deposit is received, Paybin will send a webhook notification to your CallbackUrl. The webhook contains detailed information about the transaction.

Webhook Payload

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "referenceGuid": "550e8400-e29b-41d4-a716-446655440001",
  "symbol": "ETH",
  "network": "Ethereum Mainnet",
  "amount": 0.1,
  "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "txId": "0x1234567890abcdef...",
  "status": "confirmed",
  "confirmations": 12,
  "timestamp": "2024-01-15T10:30:00Z",
  "price": {
    "usd": 2500.00,
    "eur": 2200.00
  }
}

Webhook Security

To verify the authenticity of webhooks, Paybin includes a signature in the request headers:

// Verify webhook signature
function verifyWebhookSignature(payload, signature, secretKey) {
  const expectedSignature = CryptoJS.HmacSHA256(JSON.stringify(payload), secretKey).toString();
  return signature === expectedSignature;
}

Webhook Response

Your webhook endpoint should return a 200 OK response to acknowledge receipt. If Paybin doesn't receive a successful response, it will retry the webhook up to 3 times.

Always verify webhook signatures and implement idempotency to handle duplicate webhook notifications.

Best Practices

🔐 Security

  • Always verify hash signatures for deposit address creation
  • Implement webhook signature verification
  • Use HTTPS for all API communications
  • Store API keys securely

📊 Monitoring

  • Monitor webhook delivery status
  • Track deposit confirmations
  • Set up alerts for failed transactions
  • Log all deposit events for audit purposes

💰 User Experience

  • Display minimum deposit amounts to users
  • Show real-time price information
  • Provide clear instructions for deposits
  • Implement proper error handling

🔄 Integration

  • Use unique ReferenceId values for each deposit
  • Implement proper error handling and retries
  • Cache deposit addresses when appropriate
  • Monitor API rate limits

Was this page helpful?