Initiate Payout

This endpoint initiates a payout transaction from the customer company to a beneficiary.

This API necessitates an additional layer of security; a Signature header is required. Please refer to this link for further details.

Method

POST

URL

{{BASE_URL}}/v1/payouts/initiate_payout/

Headers

KeyDescription
X-API-KEYCustomer’s API Key
SignatureRequest Body Signed with API_SECRET_KEY. Check Appendix Signature Section.

Payload Parameters

request_timestamp

Description

Request timestamp in UTC zone.

Type

DateTime (Iso Format)

Required

YES

Example

"request_timestamp": "2024-08-03T12:07:22.714321"

customer_reference

Description

Customer’s Payout reference.

Type

String

Required

NO

Example

"customer_reference": "36786798",

amount

Description

Payout Amount

Type

Decimal

Required

YES

Example

"amount": 9600.0,

currency

Description

Payout Currency

Type

Enum Currency

Required

YES

Example

"currency": "EGP",

bank_code

Description

Receiver’s Bank Code

Type

Enum Bank Codes

Required

If payout_type is set to BANK_ACCOUNT

Example

"bank_code": "CIB",

payout_type

Description

Payout Type

Type

Enum Payout Types

Required

YES

Example

"payout_type": "WALLET",

receiver_identifier

Description

Receiver Identifier (Account Number, Wallet Phone Number)

Type

String

Required

YES

Example

"receiver_identifier": "01XXXXXXXXX",

receiver_name

Description

Receiver’s Name.

Type

String

Required

YES

Example

"receiver_name": "John Doe",

receiver_phone

Description

Receiver Phone Number.
Should be provided with Country Code, if not, the Country Code will be defaulted to “+20” Egypt’s country code.

Type

String

Required

YES

Example

"receiver_phone": "+201XXXXXXXXX",

description

Description

Payout description/reason.

Type

String

Required

YES

Example

"description": "August Salary"

Payload examples

Wallet Payout

{
  "request_timestamp": "2024-08-03T12:07:22.714321",
  "customer_reference": "36786798",
  "amount": 9600.0,
  "currency": "EGP",
  "payout_type": "WALLET",
  "receiver_identifier": "01XXXXXXXXX",
  "receiver_phone": "+201XXXXXXXXX",
  "receiver_name": "Mohie Emad",
  "description": "August Salary"
}

Bank Account

{
  "request_timestamp": "2024-08-03T12:07:22.714321",
  "customer_reference": "36786798",
  "amount": 9600.0,
  "currency": "EGP",
  "bank_code": "CIB",
  "payout_type": "BANK_ACCOUNT",
  "receiver_identifier": "55000987651425623",
  "receiver_name": "Mohie Emad",
  "receiver_phone": "+201XXXXXXXXX",
  "description": "August Salary"
}

Response Fields

success

Description

This signifies Whether the payout initiation was successful or not.

Type

Boolean

message

Description

An informatory message.

Type

String

payout

Description

Payout details.

Type

Payout JSON

Success response

Status Code 201

{
  "success": true,
  "message": "Funds transfer initiated successfully.",
  "payout": {
    "id": "37c23ed0-5001-11ef-9454-0242ac120002",
    "customer_reference": "123456",
    "created": "2024-08-03T12:07:22.714321",
    "bank": {
      "name": "Commercial International Bank - Egypt S.A.E",
      "code": "CIB"
    },
    "receiver_name": "Ali Ahmed Mohamed Ahmed",
    "receiver_phone": "+201XXXXXXXXX",
    "receiver_identifier": "12345678901234",
    "amount": 1576.85,
    "fixed_fee": 10,
    "variable_fee": 15.77,
    "total_amount": 1551.08,
    "currency": "EGP",
    "status": "SETTLED",
    "payout_type": "BANK_ACCOUNT",
    "description": "Subscription Fees"
  }
}

see also

Initiate payout: errors and exceptions