Transfers API

The Transfers API allows you to move money from your merchant balance to a pre-created recipient. Transfers are queued for processing via the payment provider.

The Transfer Object

{
  "id": "tr_abc123def456",
  "object": "transfer",
  "amount": 100,
  "currency": "GHS",
  "fee": 1.50,
  "status": "pending",
  "recipient": {
    "id": "rcp_xyz789",
    "name": "John Doe",
    "account": {
      "type": "mobile_money",
      "number": "024****567",
      "provider": "mtn"
    }
  },
  "description": "Monthly payout",
  "statement_descriptor": null,
  "source_payment": null,
  "metadata": {},
  "failure_reason": null,
  "created_at": "2024-01-15T10:00:00Z",
  "completed_at": null
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"transfer"`
`amount`	number	Amount in GHS
`currency`	string	Currency code (`GHS`)
`fee`	number	Transaction fee in GHS
`status`	string	`created`, `pending`, `processing`, `completed`, `failed`, `reversed`
`recipient`	object	Recipient details
`description`	string	Transfer description
`statement_descriptor`	string	Statement description
`source_payment`	string	Linked payment ID
`metadata`	object	Custom metadata
`failure_reason`	string	Error message if failed
`created_at`	string	Creation timestamp
`completed_at`	string	Completion timestamp

Create a Transfer

POST /v1/transfers

Request Body

Parameter	Type	Required	Description
`amount`	number	Yes	Amount in GHS
`currency`	string	No	Currency (default: `GHS`)
`recipient`	string	Yes	Recipient ID
`description`	string	No	Transfer description
`statement_descriptor`	string	No	Statement description
`source_payment`	string	No	Payment ID to link this transfer to
`metadata`	object	No	Custom metadata

Use the X-Idempotency-Key header to prevent duplicate transfers.

curl -X POST https://api.shikacreators.com/v1/transfers \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "recipient": "rcp_xyz789",
    "description": "Monthly payout"
  }'

const transfer = await shikacreators.transfers.create({
  amount: 100,
  recipient: 'rcp_xyz789',
  description: 'Monthly payout'
})

transfer = client.transfers.create(
    amount=100,
    recipient='rcp_xyz789',
    description='Monthly payout'
)

Retrieve a Transfer

GET /v1/transfers/:id

List Transfers

GET /v1/transfers

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100, default 10)
`starting_after`	string	Cursor for pagination
`status`	string	Filter by status
`recipient`	string	Filter by recipient ID

Reverse a Transfer

Reverses a completed transfer, refunding the amount to your merchant balance.

POST /v1/transfers/:id/reverse

Only transfers with status completed can be reversed.

curl -X POST https://api.shikacreators.com/v1/transfers/tr_abc123def456/reverse \
  -H "Authorization: Bearer sk_test_..."

const transfer = await shikacreators.transfers.reverse('tr_abc123def456')

transfer = client.transfers.reverse('tr_abc123def456')

Transfer Statuses

Status	Description
`created`	Transfer has been created
`pending`	Transfer is queued for processing
`processing`	Transfer is being processed by the provider
`completed`	Transfer was successful
`failed`	Transfer failed
`reversed`	Transfer was reversed

Transfers

On this page