Transfer Funds Between Wallets

Transfer funds between Rapyd Wallets.

If the destination wallet does not have an account for the specified currency, the account is created. If the source wallet does not have enough funds in the account for the specified currency, the transfer fails.

The status of the transfer is PEN while the transfer is pending and the transferee has not accepted the transfer.

This method triggers Transfer Funds Between Wallets Created Webhook.

If the transferee fails to respond to the transfer request, the sender must cancel the transaction with Set Transfer Response, with status set to cancel.

Note

Limitation - This feature is available for the following types of wallet:
- person
- company
- client wallet of category disburse or general
To activate this feature, contact Client Support.
This endpoint replaces the deprecated endpoint - POST /v1/account/transfer
Rapyd no longer supports the deprecated endpoint.
The code samples include successful requests (200) and bad requests (400).
- For error messages that appear due to bad requests (400), see:
  - General Errors
  - Customer Errors
- For information about unauthorized request (401) and other authentication errors, see Troubleshooting Authentication and Authorization Errors.

Parameters

Request Header Parameters

Request Body Parameters

- amount
- Amount of the transfer. Decimal.
- currency
- Three-letter ISO 4217 code for the currency used in the amount field.
- destination_ewallet
- ID of the wallet receiving the money. String starting with ewallet_.
- expiration
- Determines the day the transfer expires, in Unix time. Acceptance of the transfer must occur before the start of this day.
  14 days after creation of the transfer
- metadata
- A JSON object defined by the client. See Metadata.
- source_ewallet
- ID of the wallet sending the money. String starting with ewallet_.

Response Parameters

- amount
- Amount of the transaction, in units of the currency defined in currency. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 4217:2015.
- created_at
- Time the transaction was made, in Unix time.
- currency_code
- Three-letter ISO 4217 code for the currency used in the amount field.
- destination_ewallet_id
- ID of the wallet receiving the money. String starting with ewallet_.
- destination_phone_number
- Phone number of the owner of the wallet receiving the money, in E.164 format.
- destination_transaction_id
- ID of the transaction with regard to the destination. String starting with wt_.
- expiration
- The day the transfer expires, in Unix time.
- id
- ID of the transaction. UUID.
- metadata
- A JSON object defined by the client. See Metadata.
- response_metadata
- Metadata created with Set Transfer Response.
- source_ewallet_id
- ID of the wallet sending the money. String starting with ewallet_.
- source_transaction_id
- ID of the transaction with regard to the source. String starting with wt_.
- status
- Status of the transaction.
  CAN - Canceled. The transferor canceled the transfer.
  CLO - Closed. The transferee accepted the funds.
  DEC - Declined. The transferee rejected the transfer.
  EXP - Expired. The transferee did not respond before the transfer expired.
  HLD - Hold. Rapyd Protect is putting this transfer on hold and reviewing it.
  PEN - Pending. Waiting for the transferee to accept.
  REJ - Rejected. Rapyd Protect has rejected this transfer.
- transfer_response_at
- Time of the Set Transfer Response operation, in Unix time.

Code Samples

.NET

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var metadata = new
                {
                    merchant_defined = true
                };

                var requestObj = new
                {
                    amount = 50,
                    currency = "USD",
                    source_ewallet = "ewallet_56a273c10570528c608f2c6bcdc8ea41",
                    destination_ewallet = "ewallet_43b888d4c038a219c52f45e754139f74",
                    metadata,
                };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/ewallets/transfer", request);

                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}

JavaScript

const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const body = {
      amount: 50,
      currency: 'USD',
      source_ewallet: 'ewallet_56a273c10570528c608f2c6bcdc8ea41',
      destination_ewallet: 'ewallet_43b888d4c038a219c52f45e754139f74',
      metadata: {
        merchant_defined: true
      }
    };
    const result = await makeRequest('POST', '/v1/ewallets/transfer', body);

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}

PHP

<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

$body = [
    'amount' => '5000',
    'currency' => 'USD',
    'source_ewallet' => 'ewallet_56a273c10570528c608f2c6bcdc8ea41',
    'destination_ewallet' => 'ewallet_43b888d4c038a219c52f45e754139f74',
    'metadata' => [
        'merchant_defined' => true
    ],
  ];

try {
    $object = make_request('post', '/v1/ewallets/transfer', $body);
    var_dump($object);
} catch(Exception $e) {
    echo "Error: $e";
}
?>

Python

from pprint import pprint

from utilities import make_request

body = {
    "amount": 50,
    "currency": "USD",
    "source_ewallet": 'ewallet_56a273c10570528c608f2c6bcdc8ea41',
    "destination_ewallet": 'ewallet_43b888d4c038a219c52f45e754139f74',
    "metadata": {
        "merchant_defined": True
    }
}

results = make_request(method='post', path='/v1/ewallets/transfer', body=body)
pprint(results)

/v1/ewallets/transfer

Transfer Funds Between Wallets

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/transfer' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
    "amount": 50.00,
    "currency": "USD",
    "source_ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861",
    "destination_ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7"
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "0790e2e3-353d-42f8-9deb-f5cdff86f61c"
    },
    "data": {
        "id": "d2e90d89-60b6-456f-a6a7-5dccf7febf5e",
        "status": "PEN",
        "amount": 5,
        "currency_code": "USD",
        "destination_phone_number": null,
        "destination_ewallet_id": "ewallet_e9e973e1c8b9cd030ce573157702ff78",
        "destination_transaction_id": "",
        "source_ewallet_id": "ewallet_e67c8ad63200d781470a04107fbd7c59",
        "source_transaction_id": "wt_ad5149f340d7147f772dd763bc9af7af",
        "transfer_response_at": 0,
        "created_at": 1704631595,
        "metadata": {
            "merchant_defined": true
        },
        "response_metadata": {},
        "expiration": 0
    }
}

Transfer Funds Between Wallets with Expiration

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/transfer' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
    "amount": 5.00,
    "currency": "USD",
    "expiration": 1764090376,
    "source_ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7",
    "destination_ewallet": "ewallet_e9e973e1c8b9cd030ce573157702ff78"
}'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "b77ced2a-3c48-42e0-b38a-e82bc221e544"
    },
    "data": {
        "id": "097331ad-7ef5-4d69-98dc-f2a506c68690",
        "status": "PEN",
        "amount": 5,
        "currency_code": "USD",
        "destination_phone_number": null,
        "destination_ewallet_id": "ewallet_e9e973e1c8b9cd030ce573157702ff78",
        "destination_transaction_id": "",
        "source_ewallet_id": "ewallet_b5320c566cc4aa01fe77440ad08693f7",
        "source_transaction_id": "wt_43f3d669a79729c845f865426855aea9",
        "transfer_response_at": null,
        "created_at": 1764770020,
        "metadata": {},
        "response_metadata": {},
        "expiration": 1765979620
    }
}

Bad Request - Insufficient Funds

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/transfer' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
    "amount": 50.25,
    "currency": "BZD",
    "source_ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861",
    "destination_ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7"
}'

{
    "status": {
        "error_code": "ERROR_WALLET_INSUFFICIENT_FUNDS",
        "status": "ERROR",
        "message": "The request tried to transfer funds from a Rapyd wallet, but the wallet did not have sufficient funds in the required currency. The request was rejected. Corrective action: Transfer funds to the wallet in the required currency and resubmit the request.",
        "response_code": "ERROR_WALLET_INSUFFICIENT_FUNDS",
        "operation_id": "745c385e-2756-4348-846d-a2310003e3fa"
    }
}

Bad Request - Destination Wallet Not Found or Disabled

curl -X post 'https://sandboxapi.rapyd.net/v1/ewallets/transfer' \
-H 'access_key: your-access-key-here' \
-H 'Content-Type: application/json' \
-H 'idempotency: your-idempotency-parameter-here' \
-H 'salt: your-random-string-here' \
-H 'signature: your-calculated-signature-here' \
-H 'timestamp: your-unix-timestamp-here' \
--data-raw '{
    "amount": 50.25,
    "currency": "USD",
    "source_ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861",
    "destination_ewallet": "ewallet_b5320c566cc4aa01fe77440ad08693f7"
}'

{
    "status": {
        "error_code": "ERROR_GET_USER",
        "status": "ERROR",
        "message": "The request attempted an operation that requires a wallet, but the wallet was not found. The request was rejected. Corrective action: Use the ID of a valid wallet that has not been deleted. The ID is a string starting with 'ewallet_'.",
        "response_code": "ERROR_GET_USER",
        "operation_id": "736a8e2c-2cfe-4c76-b6a8-9170584a7742"
    }
}

In this section:

Documentation