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) Check Testing Numbers.

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

error_code

Description

error if any.

Type

String Error Code

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.",
  "error_code": null,
  "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