Transfer Money

Initiating a Payment

The Initiate outflow payment endpoint allows you to transfer funds from your balance to a beneficiary or recipient. Currently the API only supports the same currency transfer. For example, transferring funds from your GBP balance to a GBP beneficiary’s bank account.

When initiating an outflow payment, you must provide a unique reference. The reference is used to identify the transaction and prevent duplicate payments. Make sure the reference is unique, and consistently used across your system.

The following status applies to our outflow payments

Status	Description	Webhook Event
submitted	An outflow payment remains in this state until it's picked up for review (`in_review` status) or submitted to the bank (`processing` status)	Not Applicable
processing	An outflow payment status changes to processing after the payment has been submitted to the destination institution	Not Applicable
in_review	In this state, you may need to provide additional information requested by HarpFi as part of the transaction risk assessment. This would be communicated via email	Not Applicable
cancelled	An outflow payment status is cancelled when the payment is cancelled for internal reasons or per request of the customer (the business)	payment.outflow.cancelled
failed	An outflow payment status is failed when it could not be processed after submitting to the destination institution. The status description field captures the details and reason for failure	payment.outflow.failed
successful	An outflow payment status becomes successful after it has successfully been processed by the destination institution	payment.outflow.success
reversed	An outflow payment can be reversed after initially being `successful`. This usually happens as a result of a bank glitch or issues with the destination bank, account	payment.outflow.reversed

Request Body

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

Request Body Specification

Field Key	Type	Length	Description	Required
`reference`	string	50	A unique reference identifier for the payment transaction	Yes
`destinationAmount`	number	-	The amount to be transferred to the beneficiary	Yes
`destinationCurrency`	string	3	ISO 4217 currency code for the destination amount (e.g. "USD")	Yes
`purposeCode`	string	20	Payment purpose code. Required for certain countries due to regulatory requirements	-
`description`	string	100	Description of the payment	No
`statementDescriptor`	string	50	Text that appears on the beneficiary's bank statement	No
`sender`	object	-	Information about the payment sender. Do not include if your business is the sender	No
`sender.type`	string	20	Type of sender. Must be `business_entity`	Yes
`sender.reference`	string	50	Reference identifier for the sender entity	Yes
`beneficiary`	object	-	Information about the payment beneficiary	Yes
`beneficiary.reference`	string	50	Reference identifier for the beneficiary	Yes
`beneficiary.relationship`	string	20	Relationship between sender and beneficiary; This must be one of the slugs from the relationships list (e.g. "contractor", "vendor")	No
`paymentDocuments`	Array	5	file identifier of payment documents, invoices, and evidence uploaded using the upload file API	No
`webhookUrl`	string	500	URL to receive webhook notifications for this payment	No

JSON

{
    "reference": "d8bf770ab6b7b429a7fa948efuc298572955758010",
    "destinationAmount": 100.25,
    "destinationCurrency": "USD",
    "purposeCode": "employee",
    "description": "Payment for September",
    "statementDescriptor": "Monthly salary",
    "sender": {
        "type": "business_entity",
        "reference": "m8a62ka51b773fd78215cd7a975fd7"
    },
     "beneficiary": {
        "reference": "a6b3d491125cd7a79751b773fd7821",
        "relationship": "employee"
    },
    "paymentDocuments": [{
        "fileIdentifier": "1762919288294JMl64mnLjXKoEEROi4wD.jpg"
    }],
    "webhookUrl": "https://fake.randomestuff.org"
}

Response Body

JSON

{
    "success": true,
    "message": "Payment successfully initiated",
    "data": {
        "status": "submitted",
        "reference": "d8bf770ab6b7b429a7fa948efuc298572955758010",
        "id": "TPO_8wMSvIhlVnhc"
    }
}

Payment Purpose

When initiating an outflow payment, you can supply an optional payment purpose code.

This information is required if you need to make payment to certain countries due to regulatory requirements.

Countries Requiring Payment Purpose Codes

The following countries require a payment purpose code to be submitted with the transaction:

Bahrain (BH)
China (CN)
India (IN)
Malaysia (MY)
United Arab Emirates (AE)

Request

GEThttps://api.harpfi.com/v1/payments/outflows/misc/payment-purpose

Response

JSON

{
    "success": true,
    "message": "Payment purpose retrieved successfully",
    "data": {
        "AE": [
            {
            "code": "ACM",
            "description": "Agency Commission"
            },
            {
            "code": "AES",
            "description": "Advance payment against EOS"
            },
            {
            "code": "AFA",
            "description": "Receipts or payments from personal residents bank account or deposits abroad"
            },
            {
            "code": "AFL",
            "description": "Receipts or payments from personal non-resident bank account in the UAE"
            },
            ...
        ]
    }
}

Beneficiary Relationship

When initiating an outflow payment, you may need to provide the relationship between the sender and the beneficiary. A list of supported relationships can be retrieved with the API below

Request

GEThttps://api.harpfi.com/v1/payments/outflows/misc/beneficiary-relationships

Response

JSON

{
    "success": true,
    "message": "Beneficiary relationships retrieved successfully",
    "data": [
        {
            "name": "Employee",
            "slug": "employee"
        },
        {
            "name": "Contractor",
            "slug": "contractor"
        },
        {
            "name": "Vendor",
            "slug": "vendor"
        },
        {
            "name": "Transferring to Subsidiary",
            "slug": "subsidiary"
        },
        {
            "name": "Other",
            "slug": "other"
        },
        ...
    ]
}

Get Payment Details

This API allows you to fetch the details for an outflow payment. To fetch details for an outflow payment, use the reference that was passed when initiating the payment.

Request

GEThttps://api.harpfi.com/v1/payments/outflows/:reference

Response

JSON

{
    "success": true,
    "message": "Payment details retrieved successfully",
    "data": {
        "id": "TPO_xJ8dTp8OOrUg",
        "reference": "d8bf770ab6b7b429a7fa948e-unique",
        "status": "submitted",
        "statusReason": null,
        "sourceCurrency": "USD",
        "sourceAmount": "110.00",
        "destinationAmount": "100.00",
        "destinationCurrency": "USD",
        "feeAmount": "10.00",
        "feeCurrency": "USD",
        "creationDate": "2025-10-21T14:05:54.000Z",
        "completionDate": "2025-10-21T15:00:54.000Z"
    }
}