# Create a Disbursement
source: https://developer.mastercard.com/mastercard-send-disbursements/documentation/use-cases/create-disbursement/index.md

This example flow shows how you use a **Disbursement API POST** request to create a disbursement. For details of using the API and sample requests and responses, see [API Reference](https://developer.mastercard.com/mastercard-send-disbursements/documentation/api-reference/disbursement/index.md).

### Example sequence {#example-sequence}

Diagram mastercard-send-sequence-disbursement-post

1. You send a [Disbursement API POST](https://developer.mastercard.com/mastercard-send-disbursements/documentation/api-reference/disbursement/index.md) request to Mastercard Send, including a unique `disbursement_reference` value that you generated for this transaction, for example 'pay_000001328'.

   API endpoint: `.../v1/partners/{partnerId}/disbursements/payment`

   Example: `.../v1/partners/ptnr_BEeCrYJHh2BXTXPy_PEtp-8DBOo/disbursements/payment`

   Your request can include a `decline_details` query parameter that determines the type of API response when a disbursement is declined. If set to 'true', a decline will be a 201 response with extra details. Otherwise, it will be a 402 error message.

   This example is a 'Business Disbursement' for $628.90 USD, so the request payload might start as follows:
   * JSON
   * XML

   ```JSON
   {
     "payment_disbursement": {
       "disbursement_reference": "pay_000001328",
       "payment_type": "BDB",
       "amount": "62890",
       "currency": "USD",
       ...
   ```

   ```XML
   <payment_disbursement>
     <disbursement_reference>pay_000001328</disbursement_reference>
     <payment_type>BDB</payment_type>
     <amount>62890</amount>
     <currency>USD</currency>
     ...
   ```

2. Mastercard Send validates your API request and checks the values against the limits and settings applicable to your implementation. If you have partnered with a Sponsor Originating Institution, this includes checking the limits set by them. If the API request fails validation, Mastercard Send stops processing the request and returns a 4xx error message with the appropriate [error code](https://developer.mastercard.com/mastercard-send-disbursements/documentation/response-error-codes/error-codes/index.md).

3. If your API request passes the validation and checks, Mastercard routes a Payment Transaction request message to the Receiving Institution that holds the receiving account.

4. The Receiving Institution validates the request, determines whether it approves the transaction, and includes its decision in a Payment Transaction response message to Mastercard.

5. If the Receiving Institution approves the transaction, it credits the receiving account.

6. Mastercard processes the response and sends a Disbursement API response to you.

The API response depends on the [disbursement status](https://developer.mastercard.com/mastercard-send-disbursements/documentation/response-error-codes/status/index.md):

|       Status       |                                                                                                                                                                                       Response type                                                                                                                                                                                        |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Approved (success) | 201 response with `status` value as 'APPROVED'.                                                                                                                                                                                                                                                                                                                                            |
| Declined           | If `decline_details` query parameter was set to 'true': 201 response with `status` value as 'DECLINED'. Some `transaction` array values indicate the decline reason, see [Network Response Codes](https://developer.mastercard.com/mastercard-send-disbursements/documentation/response-error-codes/network-response-codes/index.md). Otherwise: 402 error with `ReasonCode` as 'DECLINE'. |
| Unknown            | 202 response with `status` value as 'UNKNOWN', see [this guidance](https://developer.mastercard.com/mastercard-send-disbursements/documentation/response-error-codes/unknown-response/index.md).                                                                                                                                                                                           |

201 and 202 responses include a system-generated `id` for the disbursement, for example 'dsb_1357924680', which can be used to retrieve its details.

If you receive a 202 or 402 response, you can do a GET call after a few seconds to [retrieve](https://developer.mastercard.com/mastercard-send-disbursements/documentation/use-cases/retrieve-disbursement/index.md) the latest disbursement status and more details.