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

# Add Recipient to Batch

> Requires the `PAYMENT_METHOD.CREATE` key permission.

Adds a single recipient to a batch. For adding many at once, use [bulk add recipients](/api-reference/endpoint/payment-batches/add-recipients-bulk).

Requires the `PAYMENT_METHOD.CREATE` key permission.


## OpenAPI

````yaml POST /api/v1/payment-batch/{batchId}/recipients
openapi: 3.1.0
info:
  title: Afriex Business API
  version: 1.0.13
  description: >-
    Welcome to the Afriex Business API. This API allows you to manage customers,
    process payments, handle payouts, and receive real-time notifications via
    webhooks.


    For detailed guidance on authentication, pagination, error handling, and
    webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in
    the top bar. The guide provides a step-by-step instructions to help you
    integrate seamlessly.
  termsOfService: https://www.afriex.com/terms-and-condition
  contact:
    name: Afriex API Support
    email: support@afriex.com
    url: https://docs.afriex.com
  license:
    name: Proprietary
    url: https://www.afriex.com/terms-and-condition
servers:
  - url: https://sandbox.api.afriex.com
    description: Staging Base URL
  - url: https://api.afriex.com
    description: Production Base URL
security:
  - ApiKey: []
tags:
  - name: Customers
    description: Create and manage your customers.
  - name: Payment Methods
    description: Register and resolve customer payout and collection methods.
  - name: Transactions
    description: Create and track deposits, withdrawals, and swaps.
  - name: Balance
    description: View and top up your business wallet balances.
  - name: Rates
    description: Fetch real-time exchange rates.
  - name: Checkout Sessions
    description: Create hosted checkout sessions.
  - name: Webhooks
    description: Webhook event payloads and sandbox webhook testing.
  - name: Media
    description: Generate presigned URLs for secure file uploads.
  - name: Payment Batches
    description: >-
      Manage payment batches, their recipients and their runs.


      Where payload signing is enabled for your business, sign the JSON of the
      request body for POST and PATCH routes that take one. For GET routes with
      `page` and `limit`, and for the withdraw route, sign the query parameters
      as the server reads them, with defaults applied: a list call with no
      parameters signs `{"limit":100,"page":0}` and a withdraw with no
      `sessionId` signs `{}`. For the remaining routes (get, delete and
      remove-recipient) sign the path parameters, e.g. `{"batchId":"..."}`.
paths:
  /api/v1/payment-batch/{batchId}/recipients:
    parameters:
      - $ref: '#/components/parameters/x-api-version'
      - $ref: '#/components/parameters/x-api-signature'
      - $ref: '#/components/parameters/paymentBatchId'
    post:
      tags:
        - Payment Batches
      summary: Add one recipient to a batch
      description: Requires the `PAYMENT_METHOD.CREATE` key permission.
      operationId: addPaymentBatchRecipient
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentBatchRecipientRequest'
      responses:
        '201':
          description: The created recipient
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PaymentBatchRecipient'
        '400':
          $ref: '#/components/responses/PaymentBatchBadRequest'
        '401':
          $ref: '#/components/responses/PaymentBatchUnauthorized'
        '404':
          $ref: '#/components/responses/PaymentBatchNotFound'
components:
  parameters:
    x-api-version:
      name: x-api-version
      in: header
      required: false
      description: >-
        API version in ISO 8601 format. The only supported version is
        `2026-05-18`, which is also the default when the header is omitted. Any
        other value is rejected with a `400 Bad Request`.
      schema:
        type: string
    x-api-signature:
      name: x-api-signature
      in: header
      required: false
      description: >-
        Signature of the request payload, used for request authentication where
        payload signing is enabled for your business.
      schema:
        type: string
    paymentBatchId:
      name: batchId
      in: path
      required: true
      description: Id of a batch belonging to the calling business.
      schema:
        type: string
  schemas:
    PaymentBatchRecipientRequest:
      type: object
      description: >-
        The account to pay, in the same shape POST /api/v1/payment-method
        accepts, plus the amount to pay it in this batch.
      required:
        - channel
        - accountName
        - accountNumber
        - countryCode
        - institution
        - amount
      properties:
        channel:
          type: string
          example: BANK_ACCOUNT
        accountName:
          type: string
        accountNumber:
          type: string
        countryCode:
          type: string
          example: NG
        institution:
          type: object
          description: As on POST /api/v1/payment-method.
        amount:
          type: object
          required:
            - value
            - currencyCode
          properties:
            value:
              type: string
              example: '15000'
            currencyCode:
              type: string
              example: NGN
    PaymentBatchRecipient:
      type: object
      description: >-
        One payout in a batch. The response includes the channel, country,
        institution, account name and number, the per-run amount, and the batch
        and recipient ids. Fields not listed on this schema are not returned.
      properties:
        id:
          type: string
          description: >-
            The saved account's id. Returned when a recipient is created or
            updated; the list returns `paymentMethodId` and `recipientId`.
        paymentMethodId:
          type: string
        recipientId:
          type: string
          description: The recipient's id in this batch, used to update or remove it.
        channel:
          type: string
        countryCode:
          type: string
        accountName:
          type: string
        accountNumber:
          type: string
        institution:
          type: object
        amount:
          type: object
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
        error:
          type: string
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ErrorDetails'
    ErrorDetails:
      type: object
      properties:
        errorMessage:
          type: string
          description: Detailed/technical error message.
        friendlyMessage:
          type: string
          description: User-facing error message safe to display.
        data:
          type: object
          description: >-
            Optional caller-safe context for the error. On a customer-create
            uniqueness conflict (EMAIL_ALREADY_EXISTS /
            PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's
            id, so you can adopt it without a follow-up lookup.
          properties:
            customerId:
              type: string
              description: Id of the existing customer (on a create conflict).
  responses:
    PaymentBatchBadRequest:
      description: >-
        The request is invalid, or it came from an IP outside the business's
        whitelist or carried a bad payload signature.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentBatchUnauthorized:
      description: >-
        Missing or invalid API key, or a key without the permission this
        endpoint requires.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentBatchNotFound:
      description: No batch with this id belongs to the calling business.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Static business API key issued from the dashboard. A business can

        provision **multiple API keys**, each scoped to a configurable set of

        **permissions** (e.g. read transactions, create deposits, etc).
        Permissions are chosen per key at creation time in the

        dashboard and may be revoked by deleting the key. Requests made with a

        key that does not include the permission required by the target

        endpoint is rejected with a `401 Unauthorized` response, the same

        response an unrecognised, malformed, revoked or disabled key returns.
        The API

        does not distinguish the two cases on the wire.

        Manage your keys and their permissions under **Developer → API keys**

        in the dashboard.


        The permission each endpoint requires is below. Where several are

        listed, any one of them is enough. Keys created before permissions

        existed carry none and keep access to every endpoint.


        | Endpoint | Permission |

        | --- | --- |

        | `GET /customer`, `GET /customer/{customerId}` | `CUSTOMER.READ` |

        | `POST /customer` | `CUSTOMER.CREATE` |

        | `PATCH /customer/{customerId}`, `PATCH /customer/{customerId}/kyc`,
        `POST /customer/{customerId}/verify` | `CUSTOMER.UPDATE` |

        | `DELETE /customer/{customerId}` | `CUSTOMER.DELETE` |

        | `GET /payment-method`, `GET /payment-method/{paymentMethodId}`, `GET
        /payment-method/institution`, `GET /payment-method/institution/codes`,
        `GET /payment-method/resolve`, `GET /payment-method/virtual-account`,
        `GET /payment-method/pool-account` | `PAYMENT_METHOD.READ` |

        | `POST /payment-method`, `DELETE /payment-method/{paymentMethodId}`,
        `POST /payment-method/virtual-account`, `GET
        /payment-method/crypto-wallet` | `PAYMENT_METHOD.CREATE` |

        | `POST /transaction` | `TRANSACTION.DEPOSIT.CREATE`,
        `TRANSACTION.WITHDRAW.CREATE` or `TRANSACTION.SWAP.CREATE` |

        | `POST /transaction/{transactionId}/authorize`, `POST
        /transaction/pool-account` | `TRANSACTION.DEPOSIT.CREATE` |

        | `GET /transaction`, `GET /transaction/{transactionId}`, `GET
        /transaction/{transactionId}/advice` | `TRANSACTION.HISTORY.READ` |

        | `GET /org/balance`, `GET /org/rates` | `WALLET.BALANCES.READ` |

        | `POST /media/url` | `PAYMENT_METHOD.CREATE` |

        | `POST /sme-registration` | `COMPLIANCE.KYB.SUBMIT` |

        | `GET /sme-registration/status` | `COMPLIANCE.KYB.READ` |

        | `POST /checkout-session` | `CHECKOUT_LINK.CREATE` |

        | `GET /payment-batch`, `GET /payment-batch/{batchId}`, `GET
        /payment-batch/{batchId}/recipients` | `PAYMENT_METHOD.READ` |

        | `POST /payment-batch`, `PATCH /payment-batch/{batchId}`, `DELETE
        /payment-batch/{batchId}`, `POST /payment-batch/{batchId}/recipients`,
        `POST /payment-batch/{batchId}/recipients/bulk`, `PATCH
        /payment-batch/{batchId}/recipients/{recipientId}`, `DELETE
        /payment-batch/{batchId}/recipients/{recipientId}` |
        `PAYMENT_METHOD.CREATE` |

        | `POST /payment-batch/{batchId}/withdraw` |
        `TRANSACTION.WITHDRAW.CREATE` |

        | `GET /payment-batch/{batchId}/sessions` | `TRANSACTION.HISTORY.READ` |

        | `POST /org/balance/topup`, `POST /webhooks/trigger` | None; any valid
        key |

````