Guides
Changelog

Get Beneficiaries

Suggest Edits

Method is used to retrieve a list of all the beneficiaries available for the user, within a financial institution.

👍

Pre-Condition

You have obtained the user's permanent access token from the Exchange Token endpoint.

To read more about the authentication process and access token please refer to Authentication.

❗️

Note

Please note that this endpoint is only required if you use Create Transfer instead of the AutoFlow endpoint, and if the sender bank requires a beneficiary.

If you are still using the Create Transfer endpoint, we recommend you switch to Auto Flow.

Request

https://api.dapi.com/v2/payment/beneficiaries/get

Headers

ParameterTypeDescription
Authorization
REQUIRED		StringSet type to bearer token and the value to the accessToken obtained using the Exchange Token request

Body Parameters

ParameterTypeDescription
appSecret
REQUIRED		StringPrivate token generated at application creation
userSecret
REQUIRED		StringEncrypted version of the userKey

Request Example

{
	"appSecret": "00bae841ad979345fca2e2585c000da7eac420504d189cf63315e7a6234d45c68dbd6fff749167292cd1475622805dce7a2b979db3c16e25a2897158ee63845b1043930ff603e19deb1d2d54ad9afc3d52df241d3c4e7286244a2f98a10212e38b2e9f8b0e3a7592702fa4358fb9103b93a26dd6bb92c2be0327ac054f14becc",
	"userSecret": "DSv56dS/PB7QGJI/IGX4qKDhGVhIvQQhWo4zxTDT0gn079JlHnUSSq8NAtavX4fpHj7PGQ74BzVXBO9pFHXdSeLCMnayKLTLD0+zmMu7wfGzy+ZhkYTBe040CXWQ+AYaPhGTzfVWu3Lz6oM2QnqM9X56BbvpC80tN8Zg72VJHWC6YjazdQQ2NK0pl9+ePbmqn7PNjFKLhipgpTl7Hw3kvnLrSIC9AcXzVYQeSWYAv3LAEbECB1aNLXC0glMG2W7L2iLTMwy54wHbXXfSQlK9S6X7wmnZ0tn28H0MwMqWdLLtxvcFyYlMr3E0hqYnK4a5sU0IvF1yJAMHMBCbjw2Trnx2VMuX5IWjdxScfh+8IxWGvKl6RypksJTyNg100H+Q+j0vfKW/bOijFolZgHJtAxUowPlewK9JwoWahkbX2KTGoqQbSCh6KSzaCxdbg7ykNI5n+m6vdoWzGfZGFYjfgMX6aMInAM3b32ZAp9DlfFxRkg3oeoLBuTGTz73E51bZj9mGgD0FxkIXFPIWGx0WyxoYpMEesJeT8phNy0G82Bd7qzWCPGP4gK70jGpqfCWsvj1XZKMMMjReCdUrhtXKB4spQIFi+63WcGV7vDyWQdUTINOhmR8QfZOJoVm+VZgFiqCLI3Aa8AnoYw3UIPiheVjE5lxMulPNIP0QGMR31VY="
}

Response

📘

Note

Your responses may differ from those listed below on a case-by-case basis.

ParameterTypeDescription
operationIDStringUnique ID generated to identify a specific operation
successBooleanReturns true if request is successful and false for all else
statusEnumThe status of the operation

done - Operation Completed

failed - Operation Failed

user_input_required - Pending User Input

initialized - Operation In Progress

*For further explanation see Operation Statuses
beneficiariesArray<Beneficiaries>Returns beneficiary information per beneficiary, such as their name, iban, account number, type, and ID

Is only returned if request was successful
userInputsArray<UserInputs>Specifies the type of further information required from the user before the job can be completed

Is only returned if operation status is user_input_required
typeEnumType of error encountered

Is only returned if the request was not successful
msgStringDetailed description of the error

Is only returned if the request was not successful

Beneficiaries schema

ParameterTypeDescription
nameStringBeneficiary's name
ibanStringBeneficiary's IBAN

*Is returned if accountNumber is null
accountNumberStringBeneficiary's account number

Is returned if iban` is null
statusEnumStatus of beneficiary with the financial institution

approved

rejected

cancelled

waiting_for_confirmation

modified_for_pending_approval


For further explanation see Beneficiary Statuses
typeEnumType of beneficiary

same

local

intl
idStringBeneficiary's unique identifier

Response Example

{
    "operationID": "c90da2a2-18fa-4ae8-afe0-73f2aa4fc7de",
    "success": true,
    "status": "done",
    "beneficiaries": [
        {
            "name": "Aziz Ahmad",
            "iban": "FTQ72AEDB20201555555893",
            "accountNumber": "0201555555893",
            "type": "same",
            "status": "approved",
            "id": "CqOWurgxKH5KkrGwtg3jM1U0/MOj9BLYvgQx0DFrClAxwtynwEYHs0FxX/tFPM4kYav0wgGtdiliF3GPMsLwLw=="
        }
    ]
}

Successful Request/Response

Successful Request

{
	"appSecret": "00bae841ad979345fca2e2585c000da7eac420504d189cf63315e7a6234d45c68dbd6fff749167292cd1475622805dce7a2b979db3c16e25a2897158ee63845b1043930ff603e19deb1d2d54ad9afc3d52df241d3c4e7286244a2f98a10212e38b2e9f8b0e3a7592702fa4358fb9103b93a26dd6bb92c2be0327ac054f14becc",
	"userSecret": "DSv56dS/PB7QGJI/IGX4qKDhGVhIvQQhWo4zxTDT0gn079JlHnUSSq8NAtavX4fpHj7PGQ74BzVXBO9pFHXdSeLCMnayKLTLD0+zmMu7wfGzy+ZhkYTBe040CXWQ+AYaPhGTzfVWu3Lz6oM2QnqM9X56BbvpC80tN8Zg72VJHWC6YjazdQQ2NK0pl9+ePbmqn7PNjFKLhipgpTl7Hw3kvnLrSIC9AcXzVYQeSWYAv3LAEbECB1aNLXC0glMG2W7L2iLTMwy54wHbXXfSQlK9S6X7wmnZ0tn28H0MwMqWdLLtxvcFyYlMr3E0hqYnK4a5sU0IvF1yJAMHMBCbjw2Trnx2VMuX5IWjdxScfh+8IxWGvKl6RypksJTyNg100H+Q+j0vfKW/bOijFolZgHJtAxUowPlewK9JwoWahkbX2KTGoqQbSCh6KSzaCxdbg7ykNI5n+m6vdoWzGfZGFYjfgMX6aMInAM3b32ZAp9DlfFxRkg3oeoLBuTGTz73E51bZj9mGgD0FxkIXFPIWGx0WyxoYpMEesJeT8phNy0G82Bd7qzWCPGP4gK70jGpqfCWsvj1XZKMMMjReCdUrhtXKB4spQIFi+63WcGV7vDyWQdUTINOhmR8QfZOJoVm+VZgFiqCLI3Aa8AnoYw3UIPiheVjE5lxMulPNIP0QGMR31VY="
}

Successful Response

{
    "operationID": "c90da2a2-18fa-4ae8-afe0-73f2aa4fc7de",
    "success": true,
    "status": "done",
    "beneficiaries": [
        {
            "name": "john doe",
            "iban": "ASQ72AEDB20123155555893",
            "accountNumber": "0201555555893",
            "type": "same",
            "status": "approved",
            "id": "CqOWasd2KH5KkrGwtg3jM1U0/MOj9BLYvgQx0DFrClAxwtasd2EYHs0FxX/tFPM4kYav0wgGtdiliF3GPMsLwLw=="
        }
    ]
}

Request / Response - When User Input Required

Request - When User Input Is Required

{
	"appSecret": "00bae841ad979345fca2e2585c000da7eac420504d189cf63315e7a6234d45c68dbd6fff749167292cd1475622805dce7a2b979db3c16e25a2897158ee63845b1043930ff603e19deb1d2d54ad9afc3d52df241d3c4e7286244a2f98a10212e38b2e9f8b0e3a7592702fa4358fb9103b93a26dd6bb92c2be0327ac054f14becc",
	"userSecret": "DSv56dS/PB7QGJI/IGX4qKDhGVhIvQQhWo4zxTDT0gn079JlHnUSSq8NAtavX4fpHj7PGQ74BzVXBO9pFHXdSeLCMnayKLTLD0+zmMu7wfGzy+ZhkYTBe040CXWQ+AYaPhGTzfVWu3Lz6oM2QnqM9X56BbvpC80tN8Zg72VJHWC6YjazdQQ2NK0pl9+ePbmqn7PNjFKLhipgpTl7Hw3kvnLrSIC9AcXzVYQeSWYAv3LAEbECB1aNLXC0glMG2W7L2iLTMwy54wHbXXfSQlK9S6X7wmnZ0tn28H0MwMqWdLLtxvcFyYlMr3E0hqYnK4a5sU0IvF1yJAMHMBCbjw2Trnx2VMuX5IWjdxScfh+8IxWGvKl6RypksJTyNg100H+Q+j0vfKW/bOijFolZgHJtAxUowPlewK9JwoWahkbX2KTGoqQbSCh6KSzaCxdbg7ykNI5n+m6vdoWzGfZGFYjfgMX6aMInAM3b32ZAp9DlfFxRkg3oeoLBuTGTz73E51bZj9mGgD0FxkIXFPIWGx0WyxoYpMEesJeT8phNy0G82Bd7qzWCPGP4gK70jGpqfCWsvj1XZKMMMjReCdUrhtXKB4spQIFi+63WcGV7vDyWQdUTINOhmR8QfZOJoVm+VZgFiqCLI3Aa8AnoYw3UIPiheVjE5lxMulPNIP0QGMR31VY="
}

Response - When User Input Is Required

{
    "operationID": "47204fa6-dca6-44a5-8111-6c6489a232a2",
    "success": true,
    "status": "user_input_required",
    "userInputs": [
    {
      "answer": "",
      "id": "otp",
      "index": 0,
      "query": "Please enter a Smart Pass Token from your ENBD mobile application"
    }
    ]
}

Failed Request / Response - Invalid JSON Body

Failed Request - Invalid JSON Body

{
	"appSecret": "00bae841ad979345fca2e2585c000da7eac420504d189cf63315e7a6234d45c68dbd6fff749167292cd1475622805dce7a2b979db3c16e25a2897158ee63845b1043930ff603e19deb1d2d54ad9afc3d52df241d3c4e7286244a2f98a10212e38b2e9f8b0e3a7592702fa4358fb9103b93a26dd6bb92c2be0327ac054f14becc",
	"userSecret": "DSv56dS/PB7QGJI/IGX4qKDhGVhIvQQhWo4zxTDT0gn079JlHnUSSq8NAtavX4fpHj7PGQ74BzVXBO9pFHXdSeLCMnayKLTLD0+zmMu7wfGzy+ZhkYTBe040CXWQ+AYaPhGTzfVWu3Lz6oM2QnqM9X56BbvpC80tN8Zg72VJHWC6YjazdQQ2NK0pl9+ePbmqn7PNjFKLhipgpTl7Hw3kvnLrSIC9AcXzVYQeSWYAv3LAEbECB1aNLXC0glMG2W7L2iLTMwy54wHbXXfSQlK9S6X7wmnZ0tn28H0MwMqWdLLtxvcFyYlMr3E0hqYnK4a5sU0IvF1yJAMHMBCbjw2Trnx2VMuX5IWjdxScfh+8IxWGvKl6RypksJTyNg100H+Q+j0vfKW/bOijFolZgHJtAxUowPlewK9JwoWahkbX2KTGoqQbSCh6KSzaCxdbg7ykNI5n+m6vdoWzGfZGFYjfgMX6aMInAM3b32ZAp9DlfFxRkg3oeoLBuTGTz73E51bZj9mGgD0FxkIXFPIWGx0WyxoYpMEesJeT8phNy0G82Bd7qzWCPGP4gK70jGpqfCWsvj1XZKMMMjReCdUrhtXKB4spQIFi+63WcGV7vDyWQdUTINOhmR8QfZOJoVm+VZgFiqCLI3Aa8AnoYw3UIPiheVjE5lxMulPNIP0QGMR31VY="
}

Failed Response - Invalid JSON Body

{
  "msg": "Invalid JSON request",
  "type": "BAD_REQUEST",
  "success": false,
  "status": "failed"
}

Failed Request / Response - Invalid Secret Specified

Failed Request - Invalid Secret Specified

{
	"appSecret": "invaid_secret",
	"userSecret": "DSv56dS/PB7QGJI/IGX4qKDhGVhIvQQhWo4zxTDT0gn079JlHnUSSq8NAtavX4fpHj7PGQ74BzVXBO9pFHXdSeLCMnayKLTLD0+zmMu7wfGzy+ZhkYTBe040CXWQ+AYaPhGTzfVWu3Lz6oM2QnqM9X56BbvpC80tN8Zg72VJHWC6YjazdQQ2NK0pl9+ePbmqn7PNjFKLhipgpTl7Hw3kvnLrSIC9AcXzVYQeSWYAv3LAEbECB1aNLXC0glMG2W7L2iLTMwy54wHbXXfSQlK9S6X7wmnZ0tn28H0MwMqWdLLtxvcFyYlMr3E0hqYnK4a5sU0IvF1yJAMHMBCbjw2Trnx2VMuX5IWjdxScfh+8IxWGvKl6RypksJTyNg100H+Q+j0vfKW/bOijFolZgHJtAxUowPlewK9JwoWahkbX2KTGoqQbSCh6KSzaCxdbg7ykNI5n+m6vdoWzGfZGFYjfgMX6aMInAM3b32ZAp9DlfFxRkg3oeoLBuTGTz73E51bZj9mGgD0FxkIXFPIWGx0WyxoYpMEesJeT8phNy0G82Bd7qzWCPGP4gK70jGpqfCWsvj1XZKMMMjReCdUrhtXKB4spQIFi+63WcGV7vDyWQdUTINOhmR8QfZOJoVm+VZgFiqCLI3Aa8AnoYw3UIPiheVjE5lxMulPNIP0QGMR31VY="
}

Failed Response - Invalid Secret Specified

{
  "msg": "Invalid access token",
  "type": "UNAUTHORIZED",
  "success": false,
  "status": "failed"
}

📘

Note

*For more information and detailed breakdown of possible errors, please see Error Codes

Updated about 1 year ago