Get Transfers

Use cases

Use case 1: Verify transfer completion

Create a transfer and verify it succeeded.

Initiate transfer

   POST /v1/recipients/A/onboardings/O1/transfer

Response

{ "id": "T1", ... }

Check status

   GET /v1/transfers/T1

Response:

   {
     "id": "T1",
     "destination_onboarding": { "status": "SUCCEEDED" }
   }

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.

Load seller profile page: seller_id = "770e8400-..."
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", ... }
]

Display in UI

Date	From	To	Status
2026-01-15	seller-123	seller-456	Succeeded
2026-01-10	seller-123	seller-789	Succeeded

Use case 3: Audit transfer chain with reversals

Track an onboarding that was transferred and then reversed.

Original transfer: O1 from Recipient A to Recipient B — Transfer T1 created
Later reversed: O1 back from Recipient B to Recipient A — Transfer T2 created (reversal)
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"
  }
]

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.

“Transfer T1 failed, can you help?”
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" }
  }
}

Root cause identified: Invalid bank account on destination
Action: Ask recipient B to update bank details

Use case 5: Compliance audit

Verify all transfers for a recipient.

Request transfer report

GET /v1/recipients/770e8400-.../transfers

System returns all transfers

[
  { "id": "T1", "created_at": "...", ... },
  { "id": "T2", "created_at": "...", ... },
  { "id": "T3", "created_at": "...", ... }
]

Export to CSV for compliance records
Report includes:
- Transfer dates
- Origin/destination details
- Current status
- Provider information

Error Codes Reference

Code	HTTP Status	Description
`TRANSFER_NOT_FOUND`	404	Transfer does not exist
`RECIPIENT_NOT_FOUND`	404	Recipient does not exist
`ONBOARDING_NOT_FOUND`	404	Onboarding does not exist
`FORBIDDEN`	403	Resource belongs to different organization
`UNAUTHORIZED`	401	Invalid authentication credentials

Getting Started

Reference

Customers

Network Tokens

Customer Sessions (Enrollment)

Checkout Sessions

Payment Methods (Checkout)

Checkout Builder

Payment Methods (Direct Workflow)

PCI Proxy

Payments

Pre-Debit Notifications

3DS2 Setup

Unreferenced Refunds

Dry-run

Payment Links

Recipients for Marketplace

Sellers (Franchise)

Subscriptions

Payouts

Organizations

Reports

Installments

AI Caller

Communications Campaigns

Conversion Rate

Banking Connectivity

Webhooks

Use cases

Use case 1: Verify transfer completion

Use case 2: Display seller transfer history

Use case 3: Audit transfer chain with reversals

Use case 4: Support ticket investigation

Use case 5: Compliance audit

Error Codes Reference

​Use cases

​Use case 1: Verify transfer completion

​Use case 2: Display seller transfer history

​Use case 3: Audit transfer chain with reversals

​Use case 4: Support ticket investigation

​Use case 5: Compliance audit

​Error Codes Reference

Use cases

Use case 1: Verify transfer completion

Use case 2: Display seller transfer history

Use case 3: Audit transfer chain with reversals

Use case 4: Support ticket investigation

Use case 5: Compliance audit

Error Codes Reference