Skip to main content

​
Use cases

​
Use case 1: Verify transfer completion

Create a transfer and verify it succeeded.
  1. Initiate transfer
   POST /v1/recipients/A/onboardings/O1/transfer
Response 
{ "id": "T1", ... }
  1. Check status
   GET /v1/transfers/T1
Response: 
   {
     "id": "T1",
     "destination_onboarding": { "status": "SUCCEEDED" }
   }
  1. Result: Transfer succeeded ✓
To determine success:
  • Check destination_onboarding.status
  • SUCCEEDED: Transfer completed successfully
  • PENDING: Transfer still in progress
  • FAILED: Transfer failed

​
Use case 2: Display seller transfer history

Display all transfers for a seller in a marketplace dashboard.
  1. Load seller profile page: seller_id = "770e8400-..."
  2. Fetch transfer history
GET /v1/recipients/770e8400-.../transfers
Response 
[
  { "id": "T1", "created_at": "2026-01-15T16:59:22Z", ... },
  { "id": "T2", "created_at": "2026-01-10T08:30:00Z", ... }
]
  1. Display in UI
DateFromToStatus
2026-01-15seller-123seller-456Succeeded
2026-01-10seller-123seller-789Succeeded

​
Use case 3: Audit transfer chain with reversals

Track an onboarding that was transferred and then reversed.
  1. Original transfer: O1 from Recipient A to Recipient B — Transfer T1 created
  2. Later reversed: O1 back from Recipient B to Recipient A — Transfer T2 created (reversal)
  3. Audit trail
GET /v1/onboardings/O1/transfers
Response: 
[
  {
    "id": "T1",
    "origin_onboarding": { "id": "O1", "recipient": { "id": "A" } },
    "destination_onboarding": { "id": "O2", "recipient": { "id": "B" } },
    "created_at": "2026-01-15T10:00:00Z"
  },
  {
    "id": "T2",
    "origin_onboarding": { "id": "O2", "recipient": { "id": "B" } },
    "destination_onboarding": { "id": "O1", "recipient": { "id": "A" } },
    "created_at": "2026-01-16T11:00:00Z"
  }
]
  1. Analysis: Onboarding transferred out then reversed back

​
Use case 4: Support ticket investigation

Look up a failed transfer to identify and resolve the root cause.
  1. “Transfer T1 failed, can you help?”
  2. Look up the transfer
GET /v1/transfers/T1
Response 
{
  "id": "T1",
  "origin_onboarding": {
    "id": "O1",
    "status": "TRANSFERRED",
    "recipient": { "id": "A", "email": "seller@example.com" }
  },
  "destination_onboarding": {
    "id": "O2",
    "status": "FAILED",
    "response_message": "Invalid bank account",
    "recipient": { "id": "B", "email": "newseller@example.com" }
  }
}
  1. Root cause identified: Invalid bank account on destination
  2. Action: Ask recipient B to update bank details

​
Use case 5: Compliance audit

Verify all transfers for a recipient.
  1. Request transfer report
GET /v1/recipients/770e8400-.../transfers
  1. System returns all transfers
[
  { "id": "T1", "created_at": "...", ... },
  { "id": "T2", "created_at": "...", ... },
  { "id": "T3", "created_at": "...", ... }
]
  1. Export to CSV for compliance records
  2. Report includes:
    • Transfer dates
    • Origin/destination details
    • Current status
    • Provider information

​
Error Codes Reference

CodeHTTP StatusDescription
TRANSFER_NOT_FOUND404Transfer does not exist
RECIPIENT_NOT_FOUND404Recipient does not exist
ONBOARDING_NOT_FOUND404Onboarding does not exist
FORBIDDEN403Resource belongs to different organization
UNAUTHORIZED401Invalid authentication credentials