Transfer

        
       POST https://business.novasend.app/v1/payout

This endpoint allows a merchant to initiate a payout, which is a transfer of funds from their wallet to an external beneficiary.

Request Headers

Header	Description	Required
Authorization	Used to authenticate the API, `Basic base64(api_key:api_client)`	✅
X-Idempotency-Key	Ensures transaction uniqueness. The value must be a UUID	✅
Content-Type	`application/json`
Accept-Language	Language used for error messages. Supported values: `en`, `fr`

Request

Field	Type	Description	Required
`reference`	`string`	Unique transfer identifier (merchant-side UUID).	✅
`amount`	`number`	Amount to be transferred.	✅
`msisdn`	`string`	Recipient phone number (E.164 format).	✅
`country`	`string`	ISO country code (`CI`, `CM`).	✅
`customerName`	`string`	Recipient’s name.

 {
   "reference": "55a4e677-5700-4ed0-9a2a-9300db894ddb",
   "amount": 300,
   "msisdn": "+225000000000",
   "country": "CI",
   "customerName": "Habib"
 }

Response

{
  "id": "pr_bawy28jjce5btvu8eq1jjvmjlt",
  "type": "payout",
  "reference": "036065a8-081f-46f7-916f-3c4ba24b64a4",
  "status": "processed",
  "confirmationRequired": false,
  "confirmationStatus": "accepted",
  "paymentUrl": null,
  "customer": {
      "name": "Aristide",
      "phoneNumber": "+225xxxxxxxxx"
  },
  "isDirect": false,
  "payFee": false,
  "createdAt": "2026-01-19T09:11:42.594Z",
  "amount": 200,
  "fee": 4,
  "chargedAmount": 204,
  "currency": "XOF",
  "failure": null
}

Response Fields Description

Field	Description
id	Unique identifier of the payout transfer.
type	Transaction type — here `payout` (outgoing transfer).
reference	Merchant-provided reference used to identify the transfer.
status	Overall transfer status (`processing`, `processed`, `expired`, etc.).
confirmationRequired	Indicates whether beneficiary confirmation is required before executing the transfer.
confirmationStatus	Current confirmation state (`none`, `pending`, `accepted`, `declined`).
paymentUrl	Transfer confirmation URL (`null` if not applicable).
isDirect	Indicates whether the transfer was initiated via a direct flow.
payFee	Indicates whether fees are covered by the merchant.
createdAt	Transfer creation timestamp.
amount	Transfer amount (excluding fees).
fee	Service fees applied to the transfer.
chargedAmount	Total amount debited from the merchant account (amount + fees).
currency	Transaction currency (`XOF`, `USD`, `EUR`, etc.).
failure	Error details if the transfer failed (`null` if successful).

customer

Champ Description
name Name of the customer.
phoneNumber Customer phone number (international format).

Champ	Description
name	Name of the customer.
phoneNumber	Customer phone number (international format).

Transfer status

        
       GET https://marchand-novasend.app/v1/payout/{reference}

This endpoint allows you to check the current status of a transfer at any time.

Response

   {
      "id": "pr_bawy28jjce5btvu8eq1jjvmjlt",
      "type": "payout",
      "reference": "036065a8-081f-46f7-916f-3c4ba24b64a4",
      "status": "processed",
      "confirmationRequired": false,
      "confirmationStatus": "accepted",
      "paymentUrl": null,
      "customer": {
          "name": "Aristide",
          "phoneNumber": "+225xxxxxxxxx"
      },
      "isDirect": false,
      "payFee": false,
      "createdAt": "2026-01-19T09:11:42.594Z",
      "amount": 200,
      "fee": 4,
      "chargedAmount": 204,
      "currency": "XOF",
      "failure": null
   }

Payment Errors