Transfer to an External Recipient

Transferring funds to an external recipient involves two steps:

Create a recipient – The recipient must pass KYC before receiving funds.
Create a transfer – Initiate the transfer to the recipient.

Create a recipient

Use the Create a recipient endpoint to register a recipient. You will need to provide the recipient's bank details along with their personal or business information, depending on whether the recipient is an individual or a business entity.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/multi-currency-account/transfers/recipients \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "individual",
  "bank": {
    "accountType": "CHECKING",
    "address": {
      "addressLine1": "Example St 1.",
      "city": "New York",
      "stateProvinceRegion": "NY",
      "postalCode": "10003",
      "country": "USA"
    },
    "currency": "USD",
    "accountName": "Henry Wu",
    "accountNumber": "123456788",
    "bankName": "Bank of America",
    "routingNumber": "026009593"
  },
  "recipient": {
    "address": {
      "addressLine1": "Example St 1.",
      "city": "New York City",
      "stateProvinceRegion": "NY",
      "postalCode": "10003",
      "country": "USA"
    },
    "type": "20",
    "phone": "+185743482934",
    "email": "[email protected]",
    "name": "Henry Wu",
    "nationality": "USA",
    "occupation": "40400"
  },
  "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01"
}
'

Response:

{
    "id": "6e6316b0-630f-4775-9f6c-21bc4a0bd0fe",
    "createdAt": "2025-02-11T15:43:42.327349+00:00",
    "updatedAt": "2025-02-11T15:43:49.861+00:00",
    "status": "CREATED",
    "rejectionReasons": null,
    "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
    "type": "individual",
    "recipient": {
        "type": "20",
        "name": "Henry Wu",
        "phone": "+185743482934",
        "email": "[email protected]",
        "address": {
            "city": "New York",
            "country": "USA",
            "postalCode": "10003",
            "addressLine1": "Example St 1.",
            "stateProvinceRegion": "NY"
        },
        "nationality": "USA",
        "occupation": "40400",
        "certificationType": null,
        "certificationNumber": null,
        "certificationFrontUrl": null,
        "certificationBackUrl": null,
        "certificationIssuanceAuth": null,
        "certificationIssuanceDate": null,
        "certificationExpirationDate": null
    },
    "bank": {
        "currency": "USD",
        "accountName": "Henry Wu",
        "accountType": "CHECKING",
        "accountNumber": "123456788",
        "accountPurpose": null,
        "accountHolder": {
            "address": null,
            "phone": null,
            "govIdType": null,
            "govIdNumber": null
        },
        "bankName": "Bank of America",
        "bankCode": null,
        "branchName": null,
        "branchCode": null,
        "ifscCode": null,
        "sortCode": null,
        "address": {
        		"addressLine1": "Example St 1.",
          	"city": "New York",
          	"stateProvinceRegion": "NY",
          	"postalCode": "10003",
          	"country": "USA"
        },
        "swiftCode": null,
        "routingNumber": "026009593",
        "iban": null
    }
}

The recipient will initially have a status of CREATED. You can either poll the Get a recipient endpoint or wait for the Recipient webhook event to receive the latest recipient KYC status updates. Learn more about recipient statuses here.

Create a payout transfer

When initiating a payout transfer, you need to specify the transfer type, ensuring that it is not INTERNAL_TRANSFER, as that is used for transfers between internal Multi-Currency Accounts (which will be covered later).

Additionally, you must specify the paymentMethod to indicate whether the transfer is:

CROSS-BORDER – Uses SWIFT as the PaymentNetwork.
LOCAL – Uses the respective local payment network.

In the transfer request:

The source object represents the user sending the funds.
The destination object represents the recipient receiving the funds.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/multi-currency-account/transfers \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
	"requestId": "6d136d9a-a3cd-4f74-a7b0-a7dcbd028293",
  "type": "PAYOUT",
  "paymentMethod": "CROSS-BORDER",
  "paymentNetwork": "SWIFT",
  "feeBearer": "OUR",
  "purpose": "1001",
  "pobo": true,
  "source": {
    "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
    "amount": "10",
    "currency": "USD"
  },
  "destination": {
    "currency": "USD",
    "recipientId": "6e6316b0-630f-4775-9f6c-21bc4a0bd0fe"
  }
}
'

Response:

{
    "id": "ba1ed885-30f3-427d-a5f1-0404db7fef89",
    "createdAt": "2025-02-14T22:21:02.280578+00:00",
    "updatedAt": "2025-02-14T22:21:06.024+00:00",
    "requestId": "ba1ed885-30f3-427d-a5f1-0404db7fef89",
    "type": "PAYOUT",
    "status": "CREATED",
    "description": null,
    "paymentMethod": "CROSS-BORDER",
    "paymentNetwork": "SWIFT",
    "source": {
        "userId": "0e965562-047c-43ae-9481-fd894f7e6706",
        "amount": 11,
        "currency": "USD"
    },
    "destination": {
        "amount": 10,
        "currency": "USD",
        "recipientId": "6e6316b0-630f-4775-9f6c-21bc4a0bd0fe",
        "userId": null
    },
    "rateId": null,
    "feeBearer": "OUR",
    "purpose": "1001",
    "gpi": null,
    "failedReason": null,
    "remark": null
}

The payout transfer will initially have a status of CREATED. You can either poll the Retrieve a transfer endpoint or wait for the Transfer webhook event to receive the latest payout transfer status updates. Learn more about transfer statuses here.

Create an Internal Transfer

To create an internal transfer, set the transfer type to INTERNAL_TRANSFER and specify the destination user who will receive the funds.

Request:

curl --request POST \
     --url https://sandbox.hifibridge.com/v2/multi-currency-account/transfers \
     --header 'accept: application/json' \
     --header 'authorization: Bearer zpka_xxxxx' \
     --header 'content-type: application/json' \
     --data '
{
	"requestId": "6d136d9a-a3cd-4f74-a7b0-a7dcbd028293",
  "type": "INTERNAL_TRANSFER",
  "feeBearer": "OUR",
  "purpose": "1001",
  "source": {
    "userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01",
    "amount": "10",
    "currency": "USD"
  },
  "destination": {
    "currency": "USD",
		"userId": "7a8ac012-f5e7-45e0-bda5-851f542b2e01"
  }
}
'

Response:

{
    "id": "ba1ed885-30f3-427d-a5f1-0404db7fef89",
    "createdAt": "2025-02-14T22:21:02.280578+00:00",
    "updatedAt": "2025-02-14T22:21:06.024+00:00",
    "requestId": "ba1ed885-30f3-427d-a5f1-0404db7fef89",
    "type": "INTERNAL_TRANSFER",
    "status": "CREATED",
    "description": null,
    "paymentMethod": null,
    "paymentNetwork": null,
    "source": {
        "userId": "0e965562-047c-43ae-9481-fd894f7e6706",
        "amount": 11,
        "currency": "USD"
    },
    "destination": {
        "amount": 10,
        "currency": "USD",
      	"recipientId": null,
        "userId": "0e965562-047c-43ae-9481-fd894f7e6706"
    },
    "rateId": null,
    "feeBearer": "OUR",
    "purpose": "1001",
    "gpi": null,
    "failedReason": null,
    "remark": null
}