Manage Beneficiaries

Creating and managing beneficiaries is required before making payments for certain currencies. Check the Currency Support page to see which currencies require beneficiary creation.

Create Beneficiary

To create a beneficiary, you must submit a request with the beneficiary details. This request includes the necessary information to ensure payments are directed to the correct recipient.

Request

POSThttps://api.harpfi.com/v1/payments/outflows/beneficiaries

General Request Body

Field Key	Type	Length	Description	Required
`nickname`	string	100	A friendly name or identifier for the beneficiary	No
`reference`	string	50	A unique reference identifier for the beneficiary	Yes
`entity`	object	20	Information about the beneficiary entity (individual or business)	Yes
`entity.type`	string	20	The type of entity. Must be one of: `individual` or `business`	Yes
`entity.name`	string	200	The full name of the individual or business name	Yes
`entity.addressDetails`	object	-	Address information for the beneficiary	Yes
`entity.addressDetails.address`	string	200	Street address or address line	Yes
`entity.addressDetails.city`	string	100	City name	Yes
`entity.addressDetails.state`	string	100	State or province	No
`entity.addressDetails.countryCode`	string	2	ISO country code (e.g. "US", "GB", "DE")	Yes
`entity.addressDetails.postalCode`	string	20	Postal or ZIP code	No
`destination`	object	-	Payment destination information	Yes
`destination.type`	string	20	Type of destination. Must be `bank_account`	Yes
`destination.currency`	string	3	Currency code for the destination account (e.g. "USD", "GBP", "EUR")	Yes
`destination.bankAccount`	object	-	Bank account details (see bank account object specification below)	Yes
`destination.bankAccount.type`	string	20	Type of bank account. Valid values are `domestic`, `swift`	Yes
`destination.bankAccount.bankName`	string	200	Name of the bank	Yes
`destination.bankAccount.accountHolderName`	string	200	Name of the account holder	Yes
`destination.bankAccount.countryCode`	string	2	Bank ISO country code (e.g. "US", "GB", "DE")	Yes
`destination.bankAccount.bankAddress`	string	200	Bank street address or address line	Yes
`destination.bankAccount.bankAddressPostalCode`	string	20	Postal or ZIP code for the bank location	No

Scheme Account Request Body

Field Key	Type	Description	Required
`destination.bankAccount.type`	string	Type of bank account. Must be `swift`	Yes
`destination.bankAccount.accountNumber`	string	Account number, accepts digits and IBAN	Yes
`destination.bankAccount.swiftBic`	string	SWIFT/BIC code for the bank	Yes

JSON

{
    "nickname": "Ash Cole",
    "reference": "2831982749188",
    "entity": {
        "type": "individual", 
        "name": "Asher Ram",
        "addressDetails": {
            "address": "10b Western Gateway",
            "city": "London",
            "state": "Mumbai",
            "countryCode": "IN",
            "postalCode": "10101010"
        }
    },
    "destination": {
        "type": "bank_account",
        "currency": "USD",
        "bankAccount": {
            "type": "domestic",
            "accountNumber": "45009092",
            "wireRoutingNumber": "031204101",
            "accountHolderName": "Hello",
            "swiftBic": "REVOGB21",
            "bankName": "J.P. MORGAN (SECURITIES) LLC",
            "countryCode": "US",
            "bankAddress": "10A Western Gateway, Luton",
            "bankAddressPostalCode": "E104OY"
        }
    }
}

Response

JSON

{
    "success": true,
    "message": "Beneficiary created successfully",
    "data": {
        "id": "TPOB_2qFm9YCyBPyt",
        "reference": "2831982749188",
        "status": "active"
    }
}

Get Beneficiary Details

You can retrieve a beneficiary's details by submitting the beneficiary's reference as a query parameter. This allows you to fetch detailed information about any created beneficiary.

Request

GEThttps://api.harpfi.com/v1/payments/outflows/beneficiaries/:beneficiaryReference

Response

JSON

{
    "success": true,
    "message": "Beneficiary details retrieved successfully",
    "data": {
        "id": "TPOB_JsUUUjJFa2DN",
        "reference": "a6b3d491125cd7a79751b773fd7821",
        "nickname": "Peter",
        "status": "active",
        "name": "Peter Dury",
        "type": "individual",
        "destination": {
            "type": "bank_account",
            "currency": "USD",
            "bankAccount": {
                "type": "domestic",
                "accountNumber": "45009092",
                "swiftBic": "REVOGB21",
                "wireRoutingNumber": "031204101",
                "bankName": "J.P. MORGAN (SECURITIES) LLC"
            }
        }
    }
}