> ## Documentation Index > Fetch the complete documentation index at: https://docs.payana.la/llms.txt > Use this file to discover all available pages before exploring further. # Create Beneficiary > Crea un nuevo beneficiario (supplier). ## OpenAPI ````yaml POST /beneficiaries openapi: 3.1.0 info: title: Payana Accounts Payable API description: >- API pública para gestionar cuentas por pagar (payments) y beneficiarios (beneficiaries) en Payana, incluyendo notificaciones por webhooks cuando se procesan pagos. version: 1.0.0 servers: - url: https://api.prod.payana.cloud/public/api/v1 description: Production - url: https://api.develop.payana.cloud/public/api/v1 description: Develop security: - apiKeyAuth: [] tags: - name: Payments description: Crear y listar pagos - name: Beneficiaries description: Crear, listar y consultar beneficiarios - name: Webhooks description: Eventos de webhooks enviados por Payana - name: Banks description: Listar y consultar bancos - name: Transactions In description: Transacciones entrantes (polling, mismo formato que webhooks) - name: Documents description: Listar, consultar y operar documentos (cuentas por pagar) - name: DIAN Events description: >- Encolar eventos DIAN (030 Acuse de recibo, 031 Reclamo, 032 Recibo del bien, 033 Aceptación expresa, 034 Aceptación tácita) para documentos identificados por CUFE. El procesamiento es asíncrono. - name: Fiscal Sync description: >- Disparar y consultar sincronización de documentos fiscales desde el SAT (México) o la DIAN (Colombia). - name: Workflow Steps description: >- Resolver el paso en que está parado un documento dentro de su flujo: aprobación, clasificación o etiquetado. paths: /beneficiaries: post: tags: - Beneficiaries summary: Create beneficiary description: Crea un nuevo beneficiario (supplier). requestBody: description: Beneficiary payload required: true content: application/json: schema: $ref: '#/components/schemas/CreateBeneficiaryRequest' example: name: Acme Inc. type: supplier identifier_type: NIT identifier_number: '112233449' bank_accounts: - bank_reference: 8b1895e2-5b13-4fa1-9633-382639b6d0e3 account_number: '999999999' account_type: savings account_recipient_name: Acme Inc. account_recipient_document_number: '112233449' account_recipient_document_type: NIT contact_information: - type: email value: contacto@gmail.com - type: phone value: '+5725706683' responses: '201': description: Beneficiary created content: application/json: schema: $ref: '#/components/schemas/Beneficiary' example: reference: be07b610-c6f6-465c-8c43-c6469d3a585f name: Acme Inc. type: supplier email: contacto@gmail.com phone_number: null identifier_type: NIT identifier_number: '112233449' payment_terms: null fiscal_address: null contact_information: - type: email value: contacto@gmail.com - type: phone value: '+5725706683' bank_accounts: - reference: 35034bf9-babf-45c1-b9d1-c7267e2e02f0 bank_reference: 8b1895e2-5b13-4fa1-9633-382639b6d0e3 bank_name: Banco de Bogotá account_number: '999999999' created_at: '2025-06-01T18:00:35.194+00:00' updated_at: '2025-06-01T18:00:35.194+00:00' '400': description: Bad request / validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: CreateBeneficiaryRequest: type: object required: - type - identifier_number - name properties: type: $ref: '#/components/schemas/BeneficiaryType' identifier_type: anyOf: - $ref: '#/components/schemas/IdentifierType' - type: 'null' identifier_number: type: string name: type: string email: type: - string - 'null' phone_number: type: - string - 'null' payment_terms: type: - integer - 'null' contact_information: type: array items: $ref: '#/components/schemas/ContactInformation' bank_accounts: type: array items: $ref: '#/components/schemas/BankAccountCreate' Beneficiary: type: object required: - reference - name - identifier_number properties: reference: type: string name: type: string type: $ref: '#/components/schemas/BeneficiaryType' email: type: - string - 'null' phone_number: type: - string - 'null' identifier_type: anyOf: - $ref: '#/components/schemas/IdentifierType' - type: 'null' identifier_number: type: string payment_terms: type: - integer - 'null' fiscal_address: anyOf: - type: object properties: city_code: type: - string - 'null' city_name: type: - string - 'null' state_code: type: - string - 'null' state_name: type: - string - 'null' - type: 'null' contact_information: type: array items: $ref: '#/components/schemas/ContactInformation' bank_accounts: type: array items: $ref: '#/components/schemas/BankAccount' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time ErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: $ref: '#/components/schemas/ErrorObject' example: success: false error: code: VALIDATION_ERROR message: The request contains invalid data details: amount: - Amount must be greater than 0 beneficiary_id: - Beneficiary does not exist BeneficiaryType: type: string enum: - supplier IdentifierType: type: string description: Tipo de identificación (ej. NIT, CC, RFC). ContactInformation: type: object required: - type - value properties: reference: type: string description: Referencia del contacto (cuando aplica). type: type: string description: Tipo de contacto (ej. email, phone). value: type: string BankAccountCreate: type: object required: - bank_reference - account_number - account_type properties: bank_reference: type: string description: Referencia del banco (UUID). account_number: type: string account_type: type: string enum: - savings - checking account_recipient_name: type: - string - 'null' account_recipient_document_number: type: - string - 'null' account_recipient_document_type: anyOf: - $ref: '#/components/schemas/IdentifierType' - type: 'null' BankAccount: type: object required: - reference - bank_reference - bank_name - account_number properties: reference: type: string bank_reference: type: string description: Referencia del banco (UUID). bank_name: type: - string - 'null' account_number: type: string account_type: type: string enum: - savings - checking validation_status: type: string enum: - pending - processing - validated - rejected - validation_error account_recipient_name: type: - string - 'null' account_recipient_document_number: type: - string - 'null' account_recipient_document_type: anyOf: - $ref: '#/components/schemas/IdentifierType' - type: 'null' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time ErrorObject: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string details: anyOf: - $ref: '#/components/schemas/ErrorDetails' - type: 'null' ErrorCode: type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR ErrorDetails: type: object additionalProperties: type: array items: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: api-key description: API key provista por Payana. ````