# Create a beneficiary (/docs/api/beneficiaries/create-beneficiary)

Registers who is paid. The same account registered twice for the same customer is the same beneficiary (200 with the existing one). Account details are write-only. The country is the method's when the method has one.

The operation, from the OpenAPI contract (https://docs.caibopay.app/openapi.json):

```json

{
  "method": "POST",
  "path": "/v1/beneficiaries",
  "description": "Registers who is paid. The same account registered twice for the same customer is the same beneficiary (200 with the existing one). Account details are write-only. The country is the method's when the method has one.",
  "operationId": "createBeneficiary",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/BeneficiaryCreate"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Beneficiary"
          }
        }
      },
      "description": "The request was already made: the existing resource is returned.",
      "headers": {
        "Idempotent-Replayed": {
          "schema": {
            "enum": [
              "true"
            ],
            "type": "string"
          }
        }
      }
    },
    "201": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Beneficiary"
          }
        }
      },
      "description": "Created"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "The request is not valid."
    },
    "401": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "The API key is missing or not valid."
    },
    "403": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "The API key lacks the required scope."
    },
    "422": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "The request is well formed but cannot be carried out."
    },
    "429": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Too many requests."
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "An error on our side. Safe to retry with the same Idempotency-Key."
    },
    "503": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Temporarily unavailable or suspended. Safe to retry with the same Idempotency-Key."
    }
  },
  "summary": "Create a beneficiary",
  "tags": [
    "Beneficiaries"
  ],
  "x-required-scope": "write",
  "x-codeSamples": [
    {
      "lang": "js",
      "label": "Node.js",
      "source": "import { Caibo } from \"caibopay\";\n\nconst caibo = new Caibo(process.env.CAIBO_API_KEY);\n\nconst result = await caibo.beneficiaries.create({\n  currency: \"PEN\",\n  details: {},\n  method: \"bank_transfer\",\n});"
    },
    {
      "lang": "python",
      "label": "Python",
      "source": "import os\n\nimport caibopay\n\nclient = caibopay.Client(os.environ[\"CAIBO_API_KEY\"])\n\nresult = client.beneficiaries.create(currency=\"PEN\", details={}, method=\"bank_transfer\")"
    },
    {
      "lang": "go",
      "label": "Go",
      "source": "client, err := caibopay.NewClient(os.Getenv(\"CAIBO_API_KEY\"))\nif err != nil {\n\treturn err\n}\nctx := context.Background()\n\nresult, err := client.Beneficiaries.Create(ctx, &caibopay.BeneficiaryCreate{\n\tCurrency: \"PEN\",\n\tMethod: \"bank_transfer\",\n})\nif err != nil {\n\treturn err\n}\nfmt.Println(result)"
    }
  ]
}

```