Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getplu.com/llms.txt

Use this file to discover all available pages before exploring further.

​
May 6, 2026

​
Breaking: reference is now required on card withdrawals

The Withdraw from Card endpoint now requires a reference field in the request body. Calls missing it will receive 400 Bad Request. 
{
  "serviceCardId": "acme-card-xyz789jkl012mno",
  "amount": 25,
  "reference": "ref-test-001"
}
reference is an opaque, partner-supplied string (1–256 chars) — typically your internal user transaction id. We do not interpret or validate the contents beyond length. Action required: add a reference to every POST /partner/card/withdraw call. Existing integrations will start receiving 400 once this change deploys. reference is also accepted (optional) on POST /partner/card/fund and DELETE /partner/card/terminate/:serviceCardId.

​
New webhook event: wallet.deposit.card-withdrawal

When funds from a card withdrawal (or a card liquidation that releases a positive balance) land in your partner wallet, we now deliver a wallet.deposit.card-withdrawal event. The payload echoes the reference you sent on the originating call so you can correlate the wallet credit with the user transaction that triggered it — and immediately fan funds out to the end-user’s destination. 
{
  "event": "wallet.deposit.card-withdrawal",
  "timestamp": "2026-05-06T14:57:49.432Z",
  "data": {
    "partnerId": "service-partner-PdhFKbfvYr",
    "serviceCardId": "acme-card-xyz789jkl012mno",
    "serviceTransactionId": "acme-user-card-transactions-abc123def456ghi",
    "amount": 25,
    "fee": 0.5,
    "netAmount": 24.5,
    "currency": "USD",
    "reference": "ref-test-001"
  }
}
For card liquidations, data.source is set to "liquidation" so you can distinguish them. See Webhooks › Card Withdrawal Wallet Credit.

​
April 21, 2026

​
Breaking: Webhook event names renamed

Two partner webhook event names have been renamed to remove provider-specific branding. Update your webhook handlers immediately — the old event names are no longer emitted.
Old eventNew event
rain.user-eventuser.kyc-event
rain.transaction-eventcard.transaction-event
Payloads are unchanged. The data body — including status, type, and all other fields — is identical. Only the top-level event string changed. Action required:
  1. Update any switch / if on the event field in your webhook receiver.
  2. If you subscribe to specific events via the Set Webhook Events endpoint, re-subscribe using the new names.
  3. See Webhooks for the updated event reference and payload examples.

​
April 20, 2026

​
Crypto-funded cards now support partial withdrawals

The Withdraw from Card endpoint now accepts crypto-funded cards. Previously these cards returned 400 CRYPTO_CARD_WITHDRAW_BLOCKED and required full termination to recover any balance. Behavior is identical to float-card withdrawals: the card’s available balance is debited and the amount (minus your withdrawal fee) is credited to your partner wallet. Min $5, max $10,000 per transaction. The CRYPTO_CARD_WITHDRAW_BLOCKED error code is retired and no longer returned by the API.

​
New endpoints: USDC withdrawals from your partner wallet

You can now withdraw USDC from your partner wallet to an external Base address. Four new endpoints under Withdrawals:
  • POST /v1/partner/withdrawal — Submit a withdrawal request (requires idempotency-key header)
  • GET /v1/partner/withdrawal — List your withdrawals with optional status filter
  • GET /v1/partner/withdrawal/{id} — Retrieve a specific withdrawal
  • DELETE /v1/partner/withdrawal/{id} — Cancel a pending withdrawal and refund your wallet
How it works
  1. You submit a request — the amount is debited from your wallet immediately and the withdrawal enters pending status.
  2. An admin reviews and approves (or rejects) the request. There is no auto-approval.
  3. On approval, USDC is sent on-chain on Base. Your wallet stays debited.
  4. On rejection or your own cancellation, the amount is refunded to your wallet.
Fees and limits
  • Minimum withdrawal: $5
  • Flat fee: $0.50, deducted from the on-chain amount. If you request $100, your wallet is debited $100 and $99.50 is sent on-chain.
New webhook event The wallet.withdrawal.crypto event fires when a withdrawal reaches a terminal state (completed, cancelled, or rejected). For completed, the payload includes txHash and explorerUrl.

​
March 27, 2026

​
Delete User now supports pending/denied KYC users + fee waiver on re-creation

The Delete User endpoint now accepts users whose KYC was denied or is still pending — previously these users could not be deleted. Additionally, if you re-create a previously deleted user whose KYC was never approved, the KYC fee is waived. You are only charged again if the original user had been fully approved. See Delete User — Fee Waiver for details.

​
New endpoint: List User Cards

The List User Cards endpoint allows partners to list all cards belonging to a specific user via GET /v1/partner/card/users/{serviceId}/cards. Returns the same card summary data as List Cards, but scoped to a single user. Supports skip and limit pagination. Returns 404 USER_NOT_FOUND if the user does not exist under your partner account. The Get User endpoint now returns an optional verificationUrl field when the user has initiated KYC. This is the link the user can visit to complete identity verification. This field is only present when the user has an active KYC flow. No action required — this is an additive, backward-compatible change.

​
New endpoint: Delete User

The Delete User endpoint allows partners to permanently delete a card user via DELETE /v1/partner/card/users/{serviceId}. All cards belonging to the user must be terminated before deletion. If active cards remain, the API returns 409 ACTIVE_CARDS_EXIST with the list of card IDs that need to be terminated first.

​
March 26, 2026

​
New required field: countryCode on Create User

The Create User endpoint now requires a countryCode field — an ISO 3166-1 alpha-2 code representing the user’s country of residence (e.g. US, KE, NG). This field is passed to the KYC provider and card issuer to correctly identify the user’s region. Without it, users whose nationality differs from their country of residence may be incorrectly denied with WRONG_USER_REGION. Action required: Update your integration to include countryCode in the request body when creating users. Requests without this field will now return a validation error. 
{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "countryCode": "KE",
  ...
}