Guides
DashboardFAQSystem Status
Start typing to search…

Making Payouts using Bulk Payment Mechanism

🚧

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 Bulk Payment Mechanism

With a destination created we can make a Payout payment by calling Lean's API which will start the process of queueing the payout on bank side. Keep in mind that in contrast to the Single Payment Mechanism you can also include the beneficiary details while initiating a payment.

POST /payouts/v1/bulk-payments/

The Request Payload for this API can be found below:

{
  "account_id": "a91bad9a-b9bb-4c50-9821-53c9c88e5bb6",
  "authorize_payment": true,
  "payments": [
    {
      "payment_destination_id": "8c9c3271-c609-4768-8f6d-db13f67eea11",
      "amount": 670.14,
      "description": "refund order 433949",
    },
    {
      "destination_details": {
        "name": "Alex Khalifa",
        "iban": "AE870355336367411337523",
        "account_number": "5336367411337523",
        "swift_code": "NBADAEAAXXX",
        "address": "1 Marina Street",
        "country": "ARE",
        "city": "Dubai",
      },
      "amount": 620.14,
      "description": "refund order 232332",
    }
  ]
}

📘

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

In contrast to the Single Payment Mechanism the Authorization flow applies to ALL items in the payments list.

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

{
  "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 all payments 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 3 months ago