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

# Create beneficiary

> Save a recipient for repeat payouts.



## OpenAPI

````yaml POST /api/b2b/external-accounts
openapi: 3.1.0
info:
  title: Tanda API
  version: 1.0.0
  description: >-
    Collect and send KES payments in Kenya through M-PESA, Airtel Money and bank
    transfer.
servers:
  - url: https://api.tandapay.io
    description: Sandbox and production (your keys decide which)
security:
  - bearerAuth: []
tags:
  - name: Authentication
  - name: Account
  - name: Checkout
  - name: Collections
  - name: Payouts
  - name: Beneficiaries
  - name: Transactions
  - name: Reference data
  - name: Webhooks
paths:
  /api/b2b/external-accounts:
    post:
      tags:
        - Beneficiaries
      summary: Create beneficiary
      description: >-
        Saves a recipient so you can pay them later with only an
        `externalAccountId`. Verify details with [Account
        resolver](/api-reference/endpoint/account-resolver) before saving.
      operationId: create-external-account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                country:
                  type: string
                  description: ISO 3166-1 alpha-2 country code. Tanda supports `KE`.
                  enum:
                    - KE
                  example: KE
                currency:
                  type: string
                  description: ISO 4217 currency code. Tanda supports `KES`.
                  enum:
                    - KES
                  example: KES
                type:
                  type: string
                  description: >-
                    `payout` to save a recipient you pay; `deposit` to save a
                    customer you charge.
                  enum:
                    - payout
                    - deposit
                payload:
                  type: object
                  properties:
                    destination:
                      type: string
                      description: Payout only.
                      enum:
                        - MoMo
                        - Bank Account
                        - Paybill
                        - Till
                    payoutMethod:
                      type: object
                      properties:
                        accountName:
                          type: string
                          description: Recipient's name.
                          example: Grace Achieng
                        accountNumber:
                          type: string
                          description: >-
                            Phone number (MoMo), bank account number (Bank
                            Account), paybill account number (Paybill) or till
                            number (Till).
                          example: '254712345678'
                        code:
                          type: string
                          description: >-
                            Operator code for MoMo (`mpesa` or `airtel`), or the
                            bank code from [Get
                            banks](/api-reference/endpoint/get-banks) for Bank
                            Account.
                        businessNumber:
                          type: string
                          description: Paybill business number. Paybill only.
                      required:
                        - accountName
                        - accountNumber
                      description: Payout only.
                    firstName:
                      type: string
                      description: Deposit only.
                    lastName:
                      type: string
                      description: Deposit only.
                    phoneNumber:
                      type: string
                      description: >-
                        Deposit only. Kenyan mobile number in international
                        format without the `+`, e.g. `254712345678`.
                      example: '254712345678'
                  description: >-
                    Payout beneficiaries need `destination` and `payoutMethod`.
                    Deposit beneficiaries need `firstName`, `lastName` and
                    `phoneNumber`.
              required:
                - country
                - currency
                - type
                - payload
            examples:
              momo:
                summary: M-PESA recipient
                value:
                  country: KE
                  currency: KES
                  type: payout
                  payload:
                    destination: MoMo
                    payoutMethod:
                      accountName: Grace Achieng
                      accountNumber: '254712345678'
                      code: mpesa
              bank:
                summary: Bank recipient
                value:
                  country: KE
                  currency: KES
                  type: payout
                  payload:
                    destination: Bank Account
                    payoutMethod:
                      accountName: Kilimo Supplies Ltd
                      accountNumber: '01100123456700'
                      code: '1243'
              paybill:
                summary: Paybill recipient
                value:
                  country: KE
                  currency: KES
                  type: payout
                  payload:
                    destination: Paybill
                    payoutMethod:
                      accountName: Kenya Power
                      accountNumber: ACC-778812
                      businessNumber: '888880'
              deposit:
                summary: Customer to charge
                value:
                  country: KE
                  currency: KES
                  type: deposit
                  payload:
                    firstName: Brian
                    lastName: Otieno
                    phoneNumber: '254712345678'
      responses:
        '200':
          description: Beneficiary saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Use as `externalAccountId`.
              example:
                success: true
                message: External account created successfully.
                data:
                  id: ea_9Xk2LmPq
        '400':
          description: A required field is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: payload.payoutMethod.accountNumber is required
                errorCode: VALIDATION_ERROR
        '401':
          description: Missing, invalid or expired bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: Unauthorized
components:
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          description: Human-readable; may change.
        errorCode:
          type: string
          description: Stable code to branch on.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token from Generate bearer token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.