Guides
DashboardFAQSystem Status

Making Payouts using Single Payment Mechanism

Suggest Edits

🚧

All requests are processed asynchronously on Lean’s side.

A Payout payment requires an amount, a destination (also called a Beneficiary) and a source account (the one which you connected previously on the Application Dashboard).

Create Destination

The Destination is your customer’s destination bank account which will be receiving the funds from your connected source account.

Creating a Destination can be done by calling the endpoint

POST /payouts/v1/payment/destinations

with the following payload:

{
  "name": "Alex Khalifa",
  "iban": "AE870355336367411337523",
  "account_number": "5336367411337523",
  "swift_code": "NBADAEAAXXX",
  "address": "1 Marina Street",
  "country": "ARE",
  "city": "Dubai",
}

The above are all the required fields (you don't need to provide account_number and swift_code if you provide a valid IBAN. For more details please check the API Reference section

You will receive a web-hook of type payment_source.beneficiary.created once the destination has been successfully created in your connected bank account.

{
  "payload": {
    "id": "239e9eb0-57ca-4507-9e62-dd5d8ca73abd",
    "customer_id": "d3fdefba-95cf-4522-83e6-998c8b809e66",
    "payment_source_id": "a5c6b1ca-2a1a-317f-9920-7e1bf42ad945",
    "payment_destination_id": "8c9c3271-c609-4768-8f6d-db13f67eea11",
    "status": "ACTIVE",
    "end_user_id": "93b89ff7-528e-46bc-9836-8d3746a2147f",
    "payment_source_bank_identifier": "ENBD_SME_UAE"
  },
  "type": "payment_source.beneficiary.created",
  "message": "A beneficiary was added for a payment source.",
  "timestamp": "2022-08-18T07:00:00.292930078Z",
  "event_id": "78541301-8312-4fab-93f2-b95b0125f45b"
}

The above is a sample payload. For more details please check the Webhook Library

Create Payouts using Single Payment Mechanism

🚧

Ensure Destination is created

You should wait for the payment_source.beneficiary.created webhook to confirm the Beneficiary has been successfully created in the bank before initiating a Payout.

Now that we have create a destination we can make a Payout payment by calling Lean's API which will start the process of queueing the payout on bank side.

POST /payouts/v1/payment

The Request Payload for this API can be found below:

{
   "payment_details":[
      {
         "account_id": "a91bad9a-b9bb-4c50-9821-53c9c88e5bb6",
         "destination_details":
        [
            {
               "payment_destination_id": "8c9c3271-c609-4768-8f6d-db13f67eea11",
               "amount": 670.14,
               "description": "refund order 433949",
               "authorize_payment": true
            }
         ]
      }
   ]
}

📘

You can choose which Authorization flow you'd like you use by setting authorize_payment to either true or false.

Once the Payouts request is processed, you will receive a web-hooks of type payment.created:

{
  "payload": {
    "id": "e4e672fb-7f3c-43ea-be31-84195a65d0d7",
    "customer_id": "8ad2437d-2815-4b5c-82fd-543d85567668",
    "intent_id": "17e030df-91a9-4463-964c-6656605d5bcf",
    "status": "AWAITING_AUTHORIZATION",
    "amount": 670,
    "currency": "AED",
    "bank_transaction_reference": "44778733",
    "end_user_id": "85fb7de7-3e67-4e97-a2c1-13de419d003e"
  },
  "type": "payment.created",
  "message": "A payment object has been created.",
  "timestamp": "2022-10-07T10:32:39.691593783Z",
  "event_id": "cce42859-055b-4271-b4c0-b94d54a3b894"
}

☝️

The value of payload.status could be either AWAITING_AUTHORIZATION or FAILED.

More information ca be found in Payouts Lifecycle

Depending on which Auhtorization Flow you have selected, now you will either need to authorize the payment manually or Lean will do that for you. After the Authorization you will receive web-hooks of type payment.updated showing the status of the payment along with the payment information:

{
  "payload": {
    "id": "e4e672fb-7f3c-43ea-be31-84195a65d0d7",
    "customer_id": "8ad2437d-2815-4b5c-82fd-543d85567668",
    "intent_id": "17e030df-91a9-4463-964c-6656605d5bcf",
    "status": "ACCEPTED_BY_BANK",
    "amount": 670,
    "currency": "AED",
    "bank_transaction_reference": "44778733",
    "end_user_id": "eb3b08f9-4d5e-4ea3-8d28-09b4917a61a9"
  },
  "type": "payment.updated",
  "message": "A payment object has been updated.",
  "timestamp": "2022-10-07T10:43:45.128593273Z",
  "event_id": "db2d5765-a303-4f0a-8bbe-b7a4711cf60b"
}

For Automatic Authorization you need to set authorize_payment to true and Lean will queue and authorize the payment without any need for intervention.

☝️

The value of payload.status could be either AUTHORIZATION_FAILED, ACCEPTED_BY_BANK, PENDING_WITH_BANK or FAILED.

More information ca be found in Payouts Lifecycle

Updated 5 months ago

What’s Next

Check out the additional information about the different Payment Authorization flows and the difference between Single vs Bulk Payment Mechanisms.