> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oyapasteaza.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create transfer

> Send money to a resolved recipient from your Pasteaza balance.

Create a bank transfer using a previously resolved `recipientCode`. Transfers are debited from a Pasteaza wallet/source account.

<Info>
  Resolve the recipient account first. Pasteaza returns a reusable `recipientCode` that you can use for one or more transfers to the same recipient.
</Info>

## Endpoint

```http theme={null}
POST /v1/disbursements/bank-transfer
```

## Headers

```http theme={null}
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: 8f2b9d4a-3c4d-4b62-96c7-02b2c4f31388
```

## Request body

| Field                 | Type    | Required | Description                                                                                                                                                                                                        |
| --------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `recipientCode`       | string  | Yes      | Reusable recipient code returned by the Resolve Account endpoint.                                                                                                                                                  |
| `sourceAccountNumber` | string  | No       | Pasteaza wallet/source account number to debit. If omitted, Pasteaza debits your primary active NGN source account. If you do not have one yet, a default `DEFAULT_NGN_WALLET` source account is created and used. |
| `amount`              | integer | Yes      | Amount to send in kobo.                                                                                                                                                                                            |
| `narration`           | string  | No       | Transfer narration shown to the recipient.                                                                                                                                                                         |
| `merchantReference`   | string  | No       | Your internal transfer reference.                                                                                                                                                                                  |
| `metadata`            | object  | No       | Additional merchant data.                                                                                                                                                                                          |

<Info>
  `sourceAccountNumber` identifies the Pasteaza wallet/source account balance that should fund the transfer. It is not the recipient's bank account and it is not sent to the banking provider as the live debit account. For live transfers, Pasteaza uses its configured payout debit account with the provider while tracking the merchant-facing debit against your selected Pasteaza source account.
</Info>

## Example request

```bash theme={null}
curl https://api.oyapasteaza.com/v1/disbursements/bank-transfer \
  -X POST \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f2b9d4a-3c4d-4b62-96c7-02b2c4f31388" \
  -d '{
    "recipientCode": "rcp_7hK2j9xLmQ4",
    "sourceAccountNumber": "DEFAULT_NGN_WALLET",
    "amount": 500000,
    "narration": "Vendor payout",
    "merchantReference": "PAYOUT_12345",
    "metadata": {}
  }'
```

## Successful response

```json theme={null}
{
  "status": true,
  "message": "Transfer created successfully.",
  "data": {
    "reference": "pst_trf_01JABCXYZ",
    "merchantReference": "PAYOUT_12345",
    "sourceAccountNumber": "DEFAULT_NGN_WALLET",
    "amount": 500000,
    "status": "processing",
    "recipient": {
      "recipientCode": "rcp_7hK2j9xLmQ4",
      "accountNumber": "1234567890",
      "accountName": "JOHN DOE",
      "bank": {
        "code": "044",
        "name": "Access Bank Plc"
      }
    },
    "createdAt": "2026-06-11T14:30:00Z",
    "updatedAt": "2026-06-11T14:30:00Z"
  }
}
```

## Transfer flow

<Steps>
  <Step title="Resolve the recipient account">
    Send the account number and bank code to the Resolve Account endpoint.
  </Step>

  <Step title="Store the recipient code">
    Save the returned `recipientCode` for future transfers to the same recipient.
  </Step>

  <Step title="Create the transfer">
    Send the transfer request with `recipientCode`, amount, an idempotency key, and optionally `sourceAccountNumber` when you want to debit a specific Pasteaza source account.
  </Step>

  <Step title="Verify the transfer status">
    Confirm the final outcome using the Verify Transfer Status endpoint.
  </Step>
</Steps>

## Notes

* Always resolve an account before creating a transfer.
* Use `recipientCode` instead of sending raw bank account details during transfer creation.
* A `recipientCode` can be reused for multiple transfers to the same recipient.
* `sourceAccountNumber` is optional. When provided, it must belong to one of your active Pasteaza wallet/source accounts in the same environment as your API key. If it is invalid, the API returns `source_account_not_found`.
* If `sourceAccountNumber` is omitted, Pasteaza uses your primary active NGN source account, or creates and uses `DEFAULT_NGN_WALLET` when no primary source account exists.
* Use an `Idempotency-Key` to prevent duplicate transfers. Idempotency is supported for transfer creation.
* Transfers are NGN only in V1. Do not send a `currency` field.
* The response includes `sourceAccountNumber` so you can reconcile which Pasteaza source account was debited.
* A created transfer may return processing first.
* Check the final status with the Verify Transfer Status endpoint.

## Related guides

<CardGroup cols={2}>
  <Card title="Resolve account" icon="magnifying-glass" href="/disbursements/bank-transfer/resolve-account">
    Resolve a bank account and generate a recipient code.
  </Card>

  <Card title="Verify transfer status" icon="circle-check" href="/disbursements/bank-transfer/verify-transfer-status">
    Check the final status of a transfer.
  </Card>
</CardGroup>