# POST /batches/{id}/payments

This operation is used to add one or more Payments to user(s) for a specific Batch that was created using [`POST /batches`](/6dot50-apis/pay-api/batches/post-batches.md).

Validation will occur on each Payment when adding payments to a Batch. A Payment must have at least a valid MSISDN and an amount to PAY. All validation must succeed before the list of payments is added to the Batch.

Multiple payments to the same MSISDN are accepted. These payments will appear as multiple payments in the user's statement.

Payments can be made to 6DOT50 and non-6DOT50 registered members:

* Payments to **non-members** will be automatically sent a SMS once the batch is **submitted for payment**.
* Payments to **existing members**, who have the app installed, will receive a push notification that they have received a payment.

If your Pay account has been enabled with referral capability, the fields **referralAmount** and **referralMsisdn** may be used, otherwise they will be ignored.

{% hint style="info" %}
A Batch must be in DRAFT status to add any Payments to it.
{% endhint %}

### Request

Ensure the bearer token is included in the Header of the POST operation:

<table><thead><tr><th width="197.33333333333331">Header</th><th width="120">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Bearer token from <a href="/pages/cHEoeOTtlWUGg6JiSd31">/authentication/getToken</a></td></tr></tbody></table>

<table><thead><tr><th width="199.33333333333331">Parameter</th><th width="118">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>Yes</td><td>The Batch ID to add Payment(s) to</td></tr></tbody></table>

The operation accepts an array of [`Payment`](#payment)s to add to the specified Batch:

```
{
  "clearExisting": true,
  "payments": [
    {
      "msisdn": "string",
      "amount": decimal,
      "firstname": "string",
      "lastname": "string",
      "externalId": "string",
      "referralAmount": decimal,
      "referralMsisdn": "string"
    }
  ]
}
```

<table><thead><tr><th width="187">Body Field</th><th width="119.33333333333331">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>clearExisting</code></td><td>Yes</td><td>Set <code>ClearExisting</code> to <code>true</code> if you would like to remove all Payments currently in the Batch and replace them with a new list of Payments.</td></tr><tr><td><code>payments</code></td><td>Yes</td><td>One or more Payments (of type <a href="#payment"><code>Payment</code></a>) to add to the Batch.</td></tr></tbody></table>

#### Payment

<table><thead><tr><th width="199">Body Field</th><th width="119.33333333333331">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>msisdn</code></td><td>Yes</td><td>The <strong>mobile number</strong> to pay, formatted in international dialing format. e.g. 27821231234.</td></tr><tr><td><code>amount</code></td><td>Yes</td><td>The Amount to transfer to the MSISDN (up to 2 decimal places).</td></tr><tr><td><code>firstname</code></td><td>No</td><td>First name of the person to pay (optional)</td></tr><tr><td><code>lastname</code></td><td>No</td><td>Last name of the person to pay (optional)</td></tr><tr><td><code>externalId</code></td><td>No</td><td>Optional payment identifier that can be supplied by external system for tracing purposes. If supplied, the external ID must be unique.</td></tr><tr><td><code>referralAmount</code></td><td>No</td><td>The Amount to allocate to a referral (optional)</td></tr><tr><td><code>referralMsisdn</code></td><td>No</td><td>Referral MSISDN to pay (international format, e.g. 27821231234)</td></tr></tbody></table>

{% hint style="info" %}
The use of `referralAmount` and `referralMsisdn` requires your PAY account to be enabled at the Organisational level. Please contact [Support](/6dot50-apis/support-1.md) for more information.
{% endhint %}

### Response

If successful, the operation will return the following response, which includes the standard Batch response, a Summary for the Batch, as well as Payment(s) that were added to the Batch:

```
{
  "id": "string($guid)",
  "name": "string",
  "statusCode": "string",
  "externalId": "string",
  "createdAt": "string($date-time)",
  "summary": {
    "paymentsAmount": decimal,
    "paymentsCount": int32,
    "referralsAmount": decimal,
    "settledAmount": decimal,
    "settledCount": int32,
    "cancelledAmount": decimal,
    "cancelledCount": int32
  },
  "payments": [
    {
      "id": "string($guid)",
      "batchId": "string($guid)",
      "msisdn": "string",
      "amount": decimal,
      "firstname": "string",
      "lastname": "string",
      "externalId": "string",
      "statusCode": "string",
      "settledAt": "string($date-time)",
      "isMember": true,
      "referralAmount": decimal,
      "referralMsisdn": "string",
      "createdAt": "string($date-time)"
    }
  ]
}
```

<table><thead><tr><th width="178.33333333333331">Field</th><th width="202">Response Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string($guid)</td><td>Batch ID.</td></tr><tr><td><code>name</code></td><td>string</td><td>Friendly name of the Batch.</td></tr><tr><td><code>externalId</code></td><td>string</td><td>External ID of the Batch.</td></tr><tr><td><code>statusCode</code></td><td>string</td><td>Status of the Batch.</td></tr><tr><td><code>createdAt</code></td><td>string($date-time)</td><td>Date and time when the Batch was created.</td></tr><tr><td><code>summary</code></td><td><a href="#batchsummary"><code>BatchSummary</code></a> </td><td>Standard <a href="#batchsummary">Batch Summary</a> response model</td></tr><tr><td><code>payments</code></td><td><a href="#payment-1"><code>Payment</code></a></td><td>Array of <a href="#payment"><code>Payment</code></a>s in the Batch</td></tr></tbody></table>

#### BatchSummary

<table><thead><tr><th width="203.33333333333331">Field</th><th width="179">Response Type</th><th>Description</th></tr></thead><tbody><tr><td><code>paymentsAmount</code></td><td>decimal</td><td>Total value of payments to be made</td></tr><tr><td><code>paymentsCount</code></td><td>int32</td><td>Total count of payments to be made</td></tr><tr><td><code>referralsAmount</code></td><td>decimal</td><td>Total value of referral payments to be made</td></tr><tr><td><code>settledAmount</code></td><td>decimal</td><td>Total value of payments that have been settled to users (i.e. paid to their accounts). The balance (<code>paymentsAmount</code> less <code>settledAmount</code>) is the value of payments pending to non-6DOT50 members (i.e. still to join)</td></tr><tr><td><code>settledCount</code></td><td>int32</td><td>Total count of payments settled</td></tr><tr><td><code>cancelledAmount</code></td><td>decimal</td><td>Total amount of payments cancelled in the batch (e.g. by using cancel operation)</td></tr><tr><td><code>cancelledCount</code></td><td>int32</td><td>Total count of payments cancelled</td></tr></tbody></table>

#### Payment

<table><thead><tr><th width="204.66666666666666">Field</th><th width="180">Response Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string($guid)</td><td>Unique ID for the Payment. can be used to perform payment specific operations using <code>/payments</code></td></tr><tr><td><code>batchId</code></td><td>string($guid)</td><td>The Batch ID that the Payment is part of.</td></tr><tr><td><code>msisdn</code></td><td>string</td><td>The <strong>mobile number that will be paid</strong>, formatted in international dialing format. e.g. 27821231234.</td></tr><tr><td><code>amount</code></td><td>decimal</td><td>The amount that will be paid for the Payment.</td></tr><tr><td><code>firstname</code></td><td>string</td><td>Firstname of the user.</td></tr><tr><td><code>lastname</code></td><td>string</td><td>Lastname of the user.</td></tr><tr><td><code>externalId</code></td><td>string</td><td>Payment identifier supplied by external system for tracing purposes.</td></tr><tr><td><code>statusCode</code></td><td>string</td><td>Status code for the Payment. See <a href="/pages/oup1BzvVkpzt0V3mca6d#payment-status-codes">Payment Status Codes</a> for a valid list.</td></tr><tr><td><code>settledAt</code></td><td>string($date-time)</td><td>The date at which the Payment was paid into the user's account.</td></tr><tr><td><code>isMember</code></td><td>boolean</td><td>true = the user is a member of 6DOT50, false = the user is not a member of 6DOT50.</td></tr><tr><td><code>referralAmount</code></td><td>decimal</td><td>The Amount to allocate as a referral. Only applicable if Referral capability has been enabled for the Organisation.</td></tr><tr><td><code>referralMsisdn</code></td><td>string</td><td>The MSISDN of the referral. Only applicable if Referral capability has been enabled for the Organisation.</td></tr><tr><td><code>createdAt</code></td><td>string($date-time)</td><td>The date and time when the Payment instruction was created.</td></tr></tbody></table>

{% code title="Sample Response" %}

```
{
  "id": "b7ccbefd-51e1-4720-81fb-da5740e38e8c",
  "name": "Test Batch 1",
  "statusCode": "DRAFT",
  "externalId": "testbatch1",
  "createdAt": "2022-12-13T12:29:39.633",
  "summary": {
    "paymentsAmount": 23,
    "paymentsCount": 3,
    "referralsAmount": 0,
    "settledAmount": 0,
    "settledCount": 0,
    "cancelledAmount": 0,
    "cancelledCount": 0
  },
  "payments": [
    {
      "id": "cb6c2984-7b80-4964-aed7-6a12b72a7895",
      "msisdn": "27821231234",
      "amount": 10,
      "firstname": "Test",
      "lastname": "User 1",
      "statusCode": "DRAFT",
      "isMember": false
    },
    {
      "id": "4e47e31e-33e5-476e-bb9e-98bde753c207",
      "msisdn": "27821231235",
      "amount": 5,
      "firstname": "Test",
      "lastname": "User 2",
      "statusCode": "DRAFT",
      "isMember": false
    },
    {
      "id": "df5039d8-6d3e-4c64-a4e3-f5bdf12d8f1b",
      "msisdn": "27821231236",
      "amount": 8,
      "firstname": "Test",
      "lastname": "User 3",
      "statusCode": "DRAFT",
      "isMember": false
    }
  ]
}
```

{% endcode %}

### Payment Validation

Validation will occur on each payment when adding Payment(s) to a Batch. A Payment must have at least a valid MSISDN and an amount to PAY. **All validation must succeed before Payment(s) are added to the Batch.**

Should validation fail when attempting to add a Payment, a 400 Bad Request will be returned with an array of validation failures:

```
[
  {
    "errorMessage": "string",
    "fieldName": "string",
    "fieldValue": "string"
  }
]
```

<table><thead><tr><th width="217.66666666666666">Field</th><th width="165">Response Type</th><th>Description</th></tr></thead><tbody><tr><td><code>errorMessage</code></td><td>string</td><td>A friendly description of the validation error</td></tr><tr><td><code>fieldName</code></td><td>string</td><td>The Field that failed validation, .e.g msisdn</td></tr><tr><td><code>fieldValue</code></td><td>string</td><td>The Value for the field that failed validation</td></tr></tbody></table>

The following is an example payload and responses that failed validation:

{% code title="Sample Payload " %}

```
{
  "clearExisting": true,
  "payments": [
    {
      "msisdn": "0821231234",
      "amount": 10,
      "firstname": "Test",
      "lastname": "User 1"
    },
    {
      "msisdn": "27821231235",
      "amount": 5,
      "firstname": "Test",
      "lastname": "User 2"
    },
    {
      "msisdn": "27821231236",
      "firstname": "Test",
      "lastname": "User 3"
    }
  ]
}
```

{% endcode %}

{% code title="Sample Response" %}

```
[
  {
    "errorMessage": "Msisdn invalid",
    "fieldName": "Msisdn",
    "fieldValue": "0821231234"
  },
  {
    "errorMessage": "Amount must be >= 1 DZAR",
    "fieldName": "Amount",
    "fieldValue": "0.0"
  }
]
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://6dot50.gitbook.io/6dot50-apis/pay-api/batches/post-batches-id-payments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.