Paymish Loading Docs Preparing guides, collections, and live API references...
Paymish Docs

Initiate a single transfer to a user.

Topics

Endpoint Overview

Transfer

Initiate a single transfer to a user.

Initiate a single transfer by providing the necessary details such as business ID, amount, and bank information.

POST /api/transaction-service/external/v1/transfer/create-single-transfer Requires authentication

Purpose

Use this endpoint to submit initiate a single transfer to a user. It belongs to the Transfer collection and is designed for backend integrations.

Request shape

0 parameters and 8 documented body fields using application/json.

Implementation Guide

Recommended workflow

1

Authenticate first and inject a valid bearer token or secret key before calling the endpoint.

2

Validate the input data, identifiers, and account state in your application before making the request.

3

Send the POST request from your backend using the required headers and the expected content type (application/json).

4

Persist the important identifiers returned in the response so later lookups, webhooks, or support actions can be linked correctly.

Implementation notes

  • Validate the request payload on your backend before sending it, especially the 8 documented body fields.
  • Protect state-changing operations with strong validation, logging, and retry rules to avoid duplicate mutations.

Request Body

Content type: application/json

amount required
number
Amount to be transferred, in the smallest currency unit (e.g., cents). Example: 1000
bankCode required
string
Code of the bank where the recipient's account is held. Example: 999998
bankName
string
Name of the bank where the recipient's account is held. Example: Zenith Bank
accountNumber required
string
Recipient's bank account number. Example: 0051762787
accountName required
string
Name associated with the recipient's bank account. Example: Test Account
emailAddress required
string
Email address for sending transfer notifications. Example: email@example.com
transferNote
string
Optional note or memo for the transfer. Example: Payment for invoice #1234
transferReference required
string
Unique reference for the transfer transaction. Example: INV1234TRANS5678

Responses

200 Transfer successfully initiated.
400 Invalid input or missing required fields.
401 Unauthorized - Bearer token is missing or invalid.
500 Internal server error.

Expected Outcomes

200

Transfer accepted

Transfer successfully initiated.

Representative Response 
{
  "status": "success",
  "transactionId": "abcd1234efgh5678",
  "message": "Transfer initiated successfully."
}
400

Transfer blocked

Invalid input or missing required fields.

Representative Error 
{
  "status": "error",
  "message": "Invalid bank code or account number."
}
After the response:
  • Do not create a fresh reference automatically during a retry unless you intentionally want a new payout attempt.
  • Check recipient validation, approval state, and balance rules before resubmitting the transfer.
  • Monitor the stored transfer reference after a successful initiation because final payout state may still transition later.

Language Notes

Python

Use `requests` from a backend worker, service, or Django/Flask app and centralize headers in a reusable helper.

Node.js

Use `axios` or `fetch` from Node.js services only; do not place secret credentials in frontend bundles.

PHP

Wrap cURL usage in a small client class so auth headers, error handling, and logging stay consistent.

cURL

Use cURL for smoke testing and debugging, then move the final logic into your backend service code.

Code Examples

Python 
import requests

headers = {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
}
payload = {
  "amount": 1000,
  "bankCode": "999998",
  "bankName": "Zenith Bank",
  "accountNumber": "0051762787",
  "accountName": "Test Account"
}

response = requests.post(
    "https://api.paymish.com/api/transaction-service/external/v1/transfer/create-single-transfer",
    headers=headers,
    json=payload,
)

data = response.json()
print(data)
Node.js 
const axios = require("axios");

const response = await axios({
  method: "post",
  url: "https://api.paymish.com/api/transaction-service/external/v1/transfer/create-single-transfer",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  data: {
  "amount": 1000,
  "bankCode": "999998",
  "bankName": "Zenith Bank",
  "accountNumber": "0051762787",
  "accountName": "Test Account"
}
});

console.log(response.data);
cURL 
curl https://api.paymish.com/api/transaction-service/external/v1/transfer/create-single-transfer \
  -X POST \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{   "amount": 1000,   "bankCode": "999998",   "bankName": "Zenith Bank",   "accountNumber": "0051762787",   "accountName": "Test Account" }'
PHP 
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.paymish.com/api/transaction-service/external/v1/transfer/create-single-transfer");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_SECRET_KEY",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "amount" => 1000,
    "bankCode" => "999998",
    "bankName" => "Zenith Bank",
    "accountNumber" => "0051762787",
    "accountName" => "Test Account",
]));

$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);
Previous endpoint Retrieve the list of banks. Next endpoint Retrieve a list of transfers.