# Send money to a single recipient

> Create a recipient, initiate one transfer, complete OTP approval when needed, and confirm the final status.

You can transfer money in four easy steps:

- [Create a transfer recipient](#create-a-transfer-recipient)
- [Generate a transfer reference](#generate-a-transfer-reference)
- [Initiate a transfer](#initiate-a-transfer)
- [Verify a transfer](#verify-a-transfer)

<callout title="Before you begin!" type="info">

To send money on Paystack, you need API keys to authenticate your transfers. You can find your keys on the Paystack Dashboard under [Developers → API configuration](https://dashboard.paystack.com/v2/developers/api-configuration).

</callout>

## Create a transfer recipient

A transfer recipient is a beneficiary on your integration that you can send money to. Before sending money to your customer, you need to collect their details first, then use their details to [create a transfer recipient](/disbursements/transfers/recipients). The Recipients page lists the recipient types available in your market.

The `recipient_code` from the data object is the unique identifier for a user and would be used to make transfers to that customer This code should be saved with the customer's records in your database.

## Generate a transfer reference

A transfer reference is a unique identifier that lets you track, manage and reconcile each transfer request made on your integration. Transfer references allow you to prevent double crediting as you can retry a non-conclusive transfer rather than initiate a new request.

In order to take advantage of a transfer reference, you need to generate and provide it for every request. We recommend [generating a v4 UUID](https://www.uuidgenerator.net/version4) reference of no more than **50 characters**. However, here are the constraints to take note of regardless of the logic you decide to implement:

1. The reference can only contain lowercase letters (`a-z`), digits (`0-9`) and these symbols: underscore (`_`) and dash (`_`)
2. The minimum length should be **16 characters**
3. The maximum length should be **50 characters**
4. You can prepend or append special identifiers to the reference to further reduce the chances of collision

```json
{
  "source": "balance",
  "reason": "Bonus for the week",
  "amount": 100000,
  "recipient": "RCP_gd9vgag7n5lr5ix",
  "reference": "acv_9ee55786-2323-4760-98e2-6380c9cb3f68"
}
```

## Initiate a transfer

To send money to a customer, you make a `POST` request to the <api-link path="/transfer#initiate" title="Initiate Transfer">



</api-link>

 endpoint, passing the `reference` and `recipient_code` previously created.

If OTP is turned on for transfers, the transfer waits for approval. To approve it or turn OTP off for automated transfers, see [Transfer approval](/disbursements/transfers/transfer-approval).

<localized-request-response src="disbursements/transfers/initiate">



</localized-request-response>

When you send this request, if there are no errors, the response comes back with a pending status, while the transfer is being processed.

<callout title="Retrying a transfer" type="warning">

If there is an error with the transfer request, **you should retry the transaction with the same reference to avoid double crediting**. If a new `reference` is used, the transfer would be treated as a new request.

</callout>

Test transfers always return success, because there is no processing involved. The live transfers processing usually take between a few seconds and a few minutes. When it's done processing, a notification is sent to your webhook URL.

## Verify a transfer

When a transfer is initiated, it could take a few seconds or minutes to be processed. This is why we recommend relying on webhooks for verification as opposed to polling.

### Verify via webhooks

<callout title="Receiving Notifications" type="info">

In order to receive notifications, you need to [implement a webhook URL](/developer-tools/integration/webhooks#how-to-set-up-and-verify-webhooks) and set the webhook URL in [Developers → API configuration](https://dashboard.paystack.com/v2/developers/api-configuration) on your Paystack Dashboard.

</callout>

Once a transfer is processed, we send the final status of the transfer as a `POST` request to your webhook URL.

<table>
<thead>
  <tr>
    <th>
      Event
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        transfer.success
      </code>
    </td>
    
    <td>
      This is sent when the transfer is successful
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transfer.failed
      </code>
    </td>
    
    <td>
      This is sent when the transfer fails
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transfer.reversed
      </code>
    </td>
    
    <td>
      This is sent when we refund a previously debited amount for a transfer that couldn’t be completed
    </td>
  </tr>
</tbody>
</table>

<localized-snippet src="disbursements/transfers/transfer-events">



</localized-snippet>

### Verify via polling

If you prefer to use an endpoint to verify the status of the transfer, you can call the [Verify Transfer](/api/transfer#verify) endpoint with the transfer reference you used for the request:

<localized-request-response src="disbursements/transfers/verify">



</localized-request-response>

<callout title="Verification status" type="warning">

The HTTP status code you get from the API response indicates the status of the API call and not the status of the transfer. The status of the transfer is in the `data` object of the response, i.e `data.status`. The status of a transfer should only be updated with the `data.status` value when you get a **200 status code**. Check out the [how transfers work page](/disbursements/transfers/how-transfers-work) to learn more about handling transfer statuses.

</callout>

## Troubleshooting

When building or maintaining your transfer integration, keep the following integration checklist in mind:

- Ensure you have enough funds in your Paystack balance to carry out your transfers
- Ensure you are sending amount in the smallest denomination of your currency
- Ensure you have generated a transfer reference
- Implement a webhook URL to receive updates
- Ensure the recipient details are valid
- Ensure there are no long running tasks in your approval URL

Despite checking all items in the checklist, things might still not work as they should. If you encounter any issue with your integration, the first step is to check the status of the transfer.

Typically, issues occur during the validation phase or when there are multiple occurrences of an unsuccessful status. Validation errors come with descriptive messages and solutions are easy to fix. Here are some errors and solutions to them:

<table>
<thead>
  <tr>
    <th>
      Error
    </th>
    
    <th>
      Resolution
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Your reference contains illegal special characters
    </td>
    
    <td>
      Ensure that the reference contains lowercase alphanumeric characters and the only special characters are hyphen (<code>
        -
      </code>
      
      ) and underscore (<code>
        _
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      Your balance is not enough to fulfil this request
    </td>
    
    <td>
      <a href="/disbursements/transfers/balance-management">
        Top up your Paystack balance
      </a>
      
       and try again
    </td>
  </tr>
  
  <tr>
    <td>
      Sorry, we can't make the transfer to this recipient at the moment
    </td>
    
    <td>
      The customer should reach out to the bank to resolve the issues with their account
    </td>
  </tr>
  
  <tr>
    <td>
      Account closed
    </td>
    
    <td>
      The customer should reach out to the bank if they didn't close the account
    </td>
  </tr>
  
  <tr>
    <td>
      Bank code is invalid
    </td>
    
    <td>
      Ensure that you're passing the correct bank code. Use the <a href="/api/bank#list">
        list bank
      </a>
      
       endpoint to get the list of all available banks and their corresponding bank codes
    </td>
  </tr>
</tbody>
</table>

A transfer request could also be stuck in an unsuccessful status. Here's how to handle unsuccessful status:

1. `pending`: A transfer might remain in this state for a long time if there is an issue communicating with the recipient's bank. This is one of the reasons why we use queues. We keep retrying through different channels till we've exhausted all options and the transfer fails. You can also [check our status page](https://status.paystack.com/) to confirm that there's no incident.
2. `blocked`: This happens when your server fails to respond to approval request within a few seconds. If multiple transfers keep returning this status, check your approval logic to ensure that there are no long running tasks.
3. `abandoned`: A high rate of abandoned transfers means there's an OTP issue. OTP is either not being delivered or you aren't using the OTP within 30 minutes. If you are going to use OTP for approval, we recommend turning on both email and phone channels. This is to increase the chances of OTP delivery.
