Client ID

The clientId feature enables merchants to assign persistent wallet addresses to specific clients. When a clientId is provided during payment creation, the system ensures that the same wallet address is reused for all subsequent payments from that client, providing a consistent payment experience.

Use Cases

  • Recurring Payments: Clients who make multiple payments can always use the same wallet address.
  • Customer Experience: Clients can save the wallet address for future payments without requesting a new one.
  • Payment Tracking: Easier correlation of payments to specific clients in your system.
  • Integration Simplification: Your system can cache wallet addresses per client.

How It Works

Payment Creation Flow with clientId

First Payment (New Client)

  1. Client creates a payment with a unique clientId.
  2. System generates a new wallet address via Blockcore.
  3. Wallet address is associated with the provided clientId.
  4. Payment is created with status OPEN.
  5. Wallet address is returned to the client.

Subsequent Payments (Returning Client)

  1. Client creates a new payment with the same clientId.
  2. System finds the existing wallet address associated with this clientId.
  3. Any previous OPEN payments on this address are automatically expired.
  4. The same wallet address is locked for the new payment.
  5. New payment is created with status OPEN.
  6. Same wallet address is returned to the client.

Payment Status Transitions

  • Previous payment status: OPEN → EXPIRED
  • New payment status: OPEN

Note: This ensures that only one active payment exists per clientId at any given time.

API Usage

Create Payment Request

Endpoint: POST /api/v2/payments

Request Body:

{
  "amount": "100.50",
  "asset": {
    "short": "USDT",
    "network": "TRC20"
  },
  "merchant": {
    "id": 12345,
    "name": "Your Merchant Name"
  },
  "customer": {
    "id": 67890,
    "name": "John Doe",
    "email": "[email protected]"
  },
  "checkoutUrl": "https://yoursite.com/checkout",
  "clientId": "client-12345-unique-identifier"
}

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": "100.50",
  "addressTo": "TXyz123ABCdefGHIjklMNOpqrSTUvwx",
  "asset": {
    "short": "USDT",
    "network": "TRC20"
  },
  "status": "OPEN",
  "paymentRedirectUrl": "https://payment.alppay.com/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "clientId": "client-12345-unique-identifier"
}

Field Specifications

  • Field: clientId
  • Type: string
  • Required: No
  • Description: Unique identifier for the client. Can be any string value that uniquely identifies your customer (e.g., user ID, email hash, UUID)

Important Considerations

1. Previous Payment Expiration

Important: When creating a new payment with an existing clientId, any previous OPEN payment on that wallet address will be automatically marked as EXPIRED.

Example:

Time 0: Client creates Payment A with clientId="user123"
        → Wallet address X assigned
        → Payment A status: OPEN

Time 5: Client creates Payment B with clientId="user123"
        → Same wallet address X reused
        → Payment A status: OPEN → EXPIRED
        → Payment B status: OPEN

2. ClientId Format

  • No specific format requirements.
  • Recommended: Use a consistent, unique identifier from your system.

Examples:

  • User database ID: "user-12345"
  • UUID: "550e8400-e29b-41d4-a716-446655440000"
  • Email hash: "hash-md5-emailaddress"
  • Custom format: "merchant-ABC-customer-XYZ"

3. Scope and Uniqueness

The clientId is scoped to:

  • Merchant account
  • Asset (cryptocurrency)
  • Network (blockchain)

This means the same clientId can receive different wallet addresses for:

  • Different merchants
  • Different cryptocurrencies (e.g., USDT vs BTC)
  • Different networks (e.g., TRC20 vs ERC20)

Example:

clientId="user123" + Merchant A + USDT + TRC20 = Wallet Address X
clientId="user123" + Merchant A + USDT + ERC20 = Wallet Address Y
clientId="user123" + Merchant A + BTC  + BTC   = Wallet Address Z

4. Address Persistence

Once a wallet address is assigned to a clientId, it remains associated with that clientId indefinitely. The address will be reused for all future payments with the same:

  • clientId
  • Merchant
  • Asset
  • Network

5. Concurrent Payments

Only one payment can be in OPEN status per wallet address at any time. For concurrent payments for the same client:

  • Use different clientId values (e.g., "user123-session1", "user123-session2")
  • Or omit clientId to receive different wallet addresses

Webhooks and Status Updates

When a previous payment is expired due to a new payment with the same clientId, you will receive webhook notifications:

{
  "event": "payment.expired",
  "payment": {
    "id": "previous-payment-id",
    "status": "EXPIRED",
    "clientId": "user-12345",
    "addressTo": "TXyz123..."
  }
}

Then:

{
  "event": "payment.created",
  "payment": {
    "id": "new-payment-id",
    "status": "OPEN",
    "clientId": "user-12345",
    "addressTo": "TXyz123..."
  }
}

FAQ

Q: Can I change the clientId for an existing payment?

A: No, the clientId is set at payment creation and cannot be modified.

Q: What happens if a user pays to an expired payment's address?

A: The payment will still be processed and tracked. The system monitors all wallet addresses regardless of payment status.

Q: Can multiple clients share the same clientId?

A: Technically possible, but not recommended. Each client should have a unique clientId to ensure proper wallet address isolation.

Q: Is clientId case-sensitive?

A: Yes, "user123" and "User123" are treated as different values.

Q: What if I need multiple concurrent payments for the same client?

A: Either omit the clientId field, or use unique identifiers like "user123-payment1", "user123-payment2".

Q: Can I retrieve all payments for a specific clientId?

A: Yes, use the payments retrieval API with filters (implementation depends on your API version).