Programmatic Payouts to User Wallets

Automatically create customer wallets and initiate server-led USD→USDC transfers for bulk payouts and rewards distribution

Summary

Programmatically create Customers (wallets) and initiate USD→USDC transfers on behalf of each recipient; redirect each to a signed checkout URL. Post-completion, show balances and trigger business logic. KYC/compliance is handled by Swipelux.

Problem → Solution mapping

Pain	Capability	Mechanism
Need wallets for recipients	Customers API	POST /v1/customers
Push funds reliably	Server-led transfer	POST /v1/transfers → sourceInstructions.signedUrl
Event safety	Webhooks + verify	HMAC signature + REST GET /v1/transfers/`{id}`

Architecture

Implementation steps

Create or upsert recipient

curl https://wallet.swipelux.com/v1/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: sk_test_1234567890abcdef' \
  --data '{"firstName":"Ava","lastName":"Ng","email":"ava.ng@example.com","phone":"+12025550111","birthDate":"1995-05-05","residentialAddress":{"streetLine1":"45 Pine St","city":"Austin","state":"TX","postalCode":"73301","country":"US"},"identifyingInformation":[{"type":"drivers_license","issuingCountry":"US","frontSideImage":"data:image/png;base64,AAA...","backSideImage":"data:image/png;base64,BBB..."}]}'

Create transfer per recipient

curl https://wallet.swipelux.com/v1/transfers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: sk_test_1234567890abcdef' \
  --data '{"onBehalfOf":"cus_cK69MttD5nAUAbud1B","amount":"25.0","source":{"paymentRail":"card","currency":"USD"},"destination":{"currency":"USDC"}}'

Deliver checkout link

# Use sourceInstructions.signedUrl from the transfer response.
# Email/SMS it, or deep link from your app.

Verify + show balance

curl https://wallet.swipelux.com/v1/customers/cus_cK69MttD5nAUAbud1B/balances \
  --header 'X-API-Key: sk_test_1234567890abcdef'

curl https://wallet.swipelux.com/v1/webhooks \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: sk_test_1234567890abcdef' \
  --data '{ "url": "https://your-domain.com/webhook" }'

import hmac, hashlib, os, json
WEBHOOK_SECRET = os.environ['WEBHOOK_SECRET_KEY']
def verify(payload_bytes, signature_hex):
    digest = hmac.new(WEBHOOK_SECRET.encode(), payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_hex, digest)

Re-fetch and mark delivered only if state=="completed".

UX choices

If recipients are often returning, embedded widget minimizes friction using saved KYC/payment.

KPIs

Completion rate per batch; time to funds available; KYC retry rate.

Limits & caveats

USD→USDC only. Funding is via card checkout per recipient (today). Use REST as source of truth.

Troubleshooting

If a user doesn't complete checkout, state remains awaiting_funds; implement reminders and expiration.

On this page