> ## 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 Payment > Crea un nuevo pago (payment). ## OpenAPI ````yaml POST /payments 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: /payments: post: tags: - Payments summary: Create payment description: Crea un nuevo pago (payment). requestBody: description: Payment payload content: application/json: schema: $ref: '#/components/schemas/CreatePaymentRequest' example: beneficiary_reference: 8b1895e2-5b13-4fa1-9633-382639b6d0e3 amount: 10000 amount_currency: USD exchange_rate: 19 exchange_currency: USD file_path: https://example.com/image.pdf payable_payload: expiration_date: '2025-01-01' issue_date: '2025-01-01' concept: Payment of invoice 1234567890 required: true responses: '201': description: Payment created content: application/json: schema: $ref: '#/components/schemas/Payment' example: reference: 8b1895e2-5b13-4fa1-9633-382639b6d0e3 beneficiary: reference: 8b1895e2-5b13-4fa1-9633-382639b6d0e3 name: John Doe identifier_type: NIT identifier_number: '1234567890' is_deleted: true deleted_at: '2019-08-24T14:15:22Z' document: null amount: 10000 amount_currency: USD exchange_rate: 19 exchange_currency: USD status: pending file_path: https://example.com/image.jpg receipt_file_path: https://example.com/image.jpg is_archived: false payable: reference: 8b1895e2-5b13-4fa1-9633-382639b6d0e3 type: advance status: paid amount: 10000.65 amount_currency: USD file_path: https://example.com/image.pdf balance: 10000.65 issue_date: '2025-01-01' expiration_date: '2025-01-01' concept: string origin: document projects: [] batch: null tags: [] source_of_fund: null accounting_receipt: null paid_at: '2019-08-24T14:15:22Z' payment_method: cash created_at: '2019-08-24T14:15:22Z' updated_at: '2019-08-24T14:15:22Z' '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: CreatePaymentRequest: type: object required: - beneficiary_reference - amount - amount_currency - file_path - payable_payload properties: beneficiary_reference: type: string description: Referencia (UUID) del beneficiario. amount: type: integer minimum: 1 amount_currency: $ref: '#/components/schemas/Currency' exchange_rate: type: - number - 'null' exchange_currency: anyOf: - $ref: '#/components/schemas/Currency' - type: 'null' file_path: type: string format: uri payable_payload: $ref: '#/components/schemas/PayablePayload' Payment: type: object properties: reference: type: string beneficiary: anyOf: - $ref: '#/components/schemas/Beneficiary' - type: 'null' email: type: - string - 'null' document: description: >- Documento fuente del pago cuando el payable está vinculado a un documento (p. ej. factura sincronizada desde la DIAN/SAT). Es `null` en pagos manuales o anticipos sin documento asociado. anyOf: - $ref: '#/components/schemas/PaymentDocument' - type: 'null' amount: type: number amount_currency: $ref: '#/components/schemas/Currency' exchange_amount: type: - number - 'null' exchange_currency: anyOf: - $ref: '#/components/schemas/Currency' - type: 'null' exchange_rate: type: - number - 'null' status: $ref: '#/components/schemas/PaymentStatus' file_path: type: - string - 'null' receipt_file_path: type: - string - 'null' is_archived: type: boolean payable: anyOf: - $ref: '#/components/schemas/Payable' - type: 'null' batch: type: - object - 'null' tags: type: array items: $ref: '#/components/schemas/PaymentTag' source_of_fund: type: - object - 'null' accounting_receipt: type: - object - 'null' paid_at: type: - string - 'null' format: date-time payment_method: type: - string - 'null' payment_gateway: type: - string - 'null' 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 Currency: type: string enum: - USD - COP - MXN - EUR PayablePayload: type: object required: - expiration_date - issue_date - concept properties: expiration_date: type: string format: date issue_date: type: string format: date concept: type: string 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 PaymentDocument: type: object description: Resumen del documento asociado al pago a través del payable. properties: reference: type: string format: uuid description: Referencia interna del documento en Payana. type: type: string description: Tipo de documento (p. ej. `invoice`, `credit_note`). document_number: type: string description: Número de documento visible (p. ej. número de factura). fiscal_reference: type: - string - 'null' description: >- Referencia fiscal del documento (CUFE en Colombia, UUID del CFDI en México). origin: type: - string - 'null' description: Origen del documento (p. ej. `fiscal_entity`, `manual`, `api`). amount: type: number description: Monto total del documento. amount_currency: $ref: '#/components/schemas/Currency' is_canceled: type: boolean description: Indica si el documento fue cancelado ante el SAT/DIAN. PaymentStatus: type: string enum: - pending - in_process - processed - failed description: >- Estado del pago: `pending` (creado, sin procesar), `in_process` (en procesamiento), `processed` (acreditado) o `failed` (rechazado). Payable: type: object properties: reference: type: string type: type: string status: $ref: '#/components/schemas/PayableStatus' amount: type: number amount_currency: $ref: '#/components/schemas/Currency' file_path: type: - string - 'null' balance: type: - number - 'null' issue_date: type: - string - 'null' format: date expiration_date: type: - string - 'null' format: date concept: type: - string - 'null' origin: anyOf: - $ref: '#/components/schemas/PayableOrigin' - type: 'null' projects: type: array items: {} PaymentTag: type: object description: Etiqueta de un pago. properties: name: type: string ErrorObject: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string details: anyOf: - $ref: '#/components/schemas/ErrorDetails' - type: 'null' 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 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 PayableStatus: type: string enum: - pending - paid description: 'Estado del payable: `pending` (saldo pendiente) o `paid` (saldado).' PayableOrigin: type: string enum: - document - manual 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. ````