Elocuenti Payments API

openapi: 3.2.0
info:
  title: Elocuenti Payments API
  version: 1.0.0
  description: 'The public REST API of Elocuenti: contacts, conversations, funnels, WhatsApp templates, knowledge base, automations, events, AI calls, webhooks and charges (Colombia).


    Authenticate every request with `Authorization: Bearer `. A key that starts with `eloc_live_` acts in production; one that starts with `eloc_sand_` is a sandbox key: it never messages or calls your customers, and the **Sandbox** line of each operation says what it does instead. Create keys in Settings → API Keys.


    Guides and reference: https://www.elocuenti.com/api/docs'
servers:
- url: https://www.elocuenti.com
tags:
- name: payments-api
paths:
  /api/v1/payments/charges:
    post:
      tags:
      - payments-api
      summary: Create a charge
      description: 'Creates a charge and returns its payment link (`payment_url`): send it to the buyer however you want (WhatsApp, email, a button) or open it in your website with Elopay. Charge in Colombian pesos (`amount_in_cents`) or publish a price in US dollars (`price_currency: "USD"` and `price_amount`): the buyer always pays in pesos. Each status change goes to your `notification_url`, signed. Elopay is available to businesses in Colombia.


        Dollar prices, payment methods, statuses, test data and every error: https://www.elocuenti.com/api/docs/payments A business whose plan ended gets `403` with the code `SUBSCRIPTION_CANCELED`.


        **Permission:** `payments:write` · **Sandbox:** runs in the payment processor''s test environment, with no real money · **Idempotency-Key:** required · **Max body:** 5 MB'
      operationId: create_charge
      security:
      - ApiKey: []
      x-access:
        permission: payments:write
        sandbox: testEnvironment
        idempotencyKey: required
        maxBody: 5 MB
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          description: Required (`400 IDEMPOTENCY_KEY_REQUIRED` without it). Retrying with the same key returns the same charge.
          title: Idempotency-Key
        description: Required (`400 IDEMPOTENCY_KEY_REQUIRED` without it). Retrying with the same key returns the same charge.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicChargeBody'
            examples:
              link:
                summary: Payment link
                value:
                  amount_in_cents: 18990000
                  currency: COP
                  description: Order 1042
                  customer:
                    full_name: Ana Gómez
                    phone_number: '+573001234567'
                  customer_country: CO
                  external_reference: order-1042
                  notification_url: https://shop.example.com/webhooks/elocuenti
                  return_url: https://shop.example.com/orders/1042
              usd:
                summary: Price in dollars
                value:
                  price_currency: USD
                  price_amount: 7000
                  description: Gift card US$70
                  customer_country: CO
                  external_reference: order-1043
                  notification_url: https://shop.example.com/webhooks/elocuenti
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '400':
          description: 'Malformed request: a rule the JSON Schema cannot express (between fields, a required signature header that is missing) or a body that is not UTF-8. Broken JSON in UTF-8 answers **422** `json_invalid` instead.'
        '401':
          description: 'Not authenticated: the API key is missing, invalid or expired.'
        '403':
          description: Authenticated, but without permission for this resource or business.
        '409':
          description: Conflicts with the current state of the resource.
        '422':
          description: The body or the parameters fail the schema's validation.
        '429':
          description: The API key or the IP went over its request limit.
        '500':
          description: 'Internal error: there is nothing the client can change to fix it.'
        '503':
          description: 'The service cannot take the request: configuration is missing or a dependency is down. It can be retried.'
    get:
      tags:
      - payments-api
      summary: Find a charge by your reference
      description: 'Returns the charge of your `external_reference` in the key''s environment: an array with 0 or 1 charge, because the reference is unique.


        **Permission:** `payments:read` · **Sandbox:** runs in the payment processor''s test environment, with no real money'
      operationId: list_charges
      security:
      - ApiKey: []
      x-access:
        permission: payments:read
        sandbox: testEnvironment
      parameters:
      - name: external_reference
        in: query
        required: true
        schema:
          type: string
          examples:
          - order-1042
          title: External Reference
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeList'
        '401':
          description: 'Not authenticated: the API key is missing, invalid or expired.'
        '403':
          description: Authenticated, but without permission for this resource or business.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: The API key or the IP went over its request limit.
        '500':
          description: 'Internal error: there is nothing the client can change to fix it.'
  /api/v1/payments/charges/{charge_id}:
    get:
      tags:
      - payments-api
      summary: Get a charge
      description: 'Returns a charge with its real status: confirm it here before you deliver what you sold, even after the signed notification. It does not return the dollar price: keep it with your order.


        Dollar prices, payment methods, statuses, test data and every error: https://www.elocuenti.com/api/docs/payments


        **Permission:** `payments:read` · **Sandbox:** runs in the payment processor''s test environment, with no real money'
      operationId: get_charge
      security:
      - ApiKey: []
      x-access:
        permission: payments:read
        sandbox: testEnvironment
      parameters:
      - name: charge_id
        in: path
        required: true
        schema:
          type: string
          title: Charge Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '401':
          description: 'Not authenticated: the API key is missing, invalid or expired.'
        '403':
          description: Authenticated, but without permission for this resource or business.
        '404':
          description: The resource does not exist, or this business cannot see it.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: The API key or the IP went over its request limit.
        '500':
          description: 'Internal error: there is nothing the client can change to fix it.'
  /api/v1/payments/charges/{charge_id}/cancel:
    post:
      tags:
      - payments-api
      summary: Cancel a charge
      description: 'Cancels an open charge, with an optional `reason`: it answers `200` with `cancelled: true`. If the charge was already paid, cancelled or expired, you get its real status with `cancelled: false`: it is not an error. A Nequi push already on the buyer''s phone cannot be withdrawn: the answer says `cancel_requested: true` and the charge stays `pending` until the buyer approves it (`paid`) or it expires (`failed`), so keep following it.


        **Permission:** `payments:write` · **Sandbox:** runs in the payment processor''s test environment, with no real money · **Max body:** 5 MB'
      operationId: cancel_charge
      security:
      - ApiKey: []
      x-access:
        permission: payments:write
        sandbox: testEnvironment
        maxBody: 5 MB
      parameters:
      - name: charge_id
        in: path
        required: true
        schema:
          type: string
          title: Charge Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/CancelBody'
              - type: 'null'
              title: Body
            examples:
              reason:
                summary: With a reason
                value:
                  reason: The customer changed the order
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeCancellationResponse'
        '400':
          description: 'Malformed request: a rule the JSON Schema cannot express (between fields, a required signature header that is missing) or a body that is not UTF-8. Broken JSON in UTF-8 answers **422** `json_invalid` instead.'
        '401':
          description: 'Not authenticated: the API key is missing, invalid or expired.'
        '403':
          description: Authenticated, but without permission for this resource or business.
        '404':
          description: The resource does not exist, or this business cannot see it.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: The API key or the IP went over its request limit.
        '500':
          description: 'Internal error: there is nothing the client can change to fix it.'
components:
  schemas:
    ChargeMethods:
      type: object
      properties:
        checkout:
          $ref: '#/components/schemas/ChargeCheckout'
        nequi_only:
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: 'Only on creation with `method_hint: nequi`: transaction_id, status, phone_masked.'
          title: Nequi Only
        qr:
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          description: 'Only on creation with `method_hint: qr`: transaction_id, image.'
          title: Qr
      required:
      - checkout
      - nequi_only
      - qr
      title: ChargeMethods
    ChargeList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Charge'
          title: Data
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - 3f9a1c07d2b4
          title: Request Id
      required:
      - data
      title: ChargeList
    Charge:
      type: object
      properties:
        id:
          type: string
          examples:
          - 6f1c0000-0000-4000-8000-000000000040
          title: Id
        status:
          type: string
          description: pending, paid, failed, expired or cancelled.
          examples:
          - pending
          title: Status
        payment_url:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Link to send the payer: Elopay Checkout (https://elopay.elocuenti.com/c/<id>). Links issued before (https://www.elocuenti.com/api/payments/pay/<id>) redirect to it.'
          title: Payment Url
        methods:
          $ref: '#/components/schemas/ChargeMethods'
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
        amounts:
          $ref: '#/components/schemas/ChargeAmounts'
        terms:
          anyOf:
          - $ref: '#/components/schemas/ChargeTerms'
          - type: 'null'
        external_reference:
          anyOf:
          - type: string
          - type: 'null'
          title: External Reference
        payment_method:
          anyOf:
          - type: string
          - type: 'null'
          title: Payment Method
        paid_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Paid At
        provider_transaction_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Transaction Id
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
      required:
      - id
      - status
      - payment_url
      - methods
      - expires_at
      - amounts
      - terms
      description: A charge. Creation answers the first block; reads add the fields after `terms`.
      title: Charge
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
      title: HTTPValidationError
    ChargeResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Charge'
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - 3f9a1c07d2b4
          title: Request Id
      required:
      - data
      title: ChargeResponse
    ChargeCheckout:
      type: object
      properties:
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        account:
          anyOf:
          - type: string
          - type: 'null'
          title: Account
      required:
      - url
      - account
      title: ChargeCheckout
    PublicChargeBody:
      type: object
      properties:
        amount_in_cents:
          description: Amount the payer pays, in cents (COP 1.000 = 100000). Omit it to send `price_amount`.
          anyOf:
          - type: integer
            exclusiveMinimum: 0
          - type: 'null'
          title: Amount In Cents
        price_currency:
          description: 'Prices in dollars (turn it on in Charge settings): the payer pays the equivalent in COP at the day''s rate (how it is computed: Charge settings in the dashboard), held 24 h. Send it with `price_amount` instead of `amount_in_cents`.'
          anyOf:
          - type: string
            const: USD
          - type: 'null'
          title: Price Currency
        price_amount:
          description: Your price in US cents (US$70 = 7000), with `price_currency`.
          anyOf:
          - type: integer
            exclusiveMinimum: 0
            maximum: 100000000
          - type: 'null'
          title: Price Amount
        currency:
          default: COP
          type: string
          const: COP
          title: Currency
        description:
          default: ''
          description: What the payer sees on the checkout.
          type: string
          title: Description
        customer:
          description: Payer data the checkout opens with (all optional; see PublicCustomer).
          $ref: '#/components/schemas/PublicCustomer'
        customer_country:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO 3166-1 alpha-2, e.g. CO.
          title: Customer Country
        method_hint:
          default: any
          description: '`any` opens the checkout; the others start that method directly.'
          type: string
          enum:
          - any
          - nequi
          - card
          - pse
          - qr
          title: Method Hint
        allowed_methods:
          description: Methods the checkout offers; omit it for every method the account has enabled.
          anyOf:
          - minItems: 1
            type: array
            items:
              type: string
              enum:
              - card
              - nequi
              - daviplata
              - qr
              - pse
              - bancolombia
              - breb
          - type: 'null'
          title: Allowed Methods
        external_reference:
          description: 'Your id for this charge, unique per account and environment (reuse: 409).'
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: External Reference
        return_url:
          anyOf:
          - type: string
          - type: 'null'
          description: https URL the payer's browser returns to after paying.
          title: Return Url
        notification_url:
          anyOf:
          - type: string
          - type: 'null'
          description: 'https URL that receives each status change of the charge, signed with the notification secret of its environment (one for sandbox, one for production, in Settings → API Keys). Without that secret the charge is refused with 422 `WEBHOOK_SECRET_MISSING` and nothing is created: generate it and send the same request with the same Idempotency-Key. The same happens when you leave it out and your business has a default notification URL.'
          title: Notification Url
        expires_in_minutes:
          default: 1440
          description: Minutes until it expires.
          type: integer
          exclusiveMinimum: 0
          maximum: 43200
          title: Expires In Minutes
        metadata:
          description: Stored as-is, never shown.
          anyOf:
          - type: object
            additionalProperties: true
          - type: 'null'
          title: Metadata
      additionalProperties: false
      title: PublicChargeBody
    ChargeCancellation:
      type: object
      properties:
        id:
          type: string
          examples:
          - 6f1c0000-0000-4000-8000-000000000040
          title: Id
        status:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - cancelled
          title: Status
        cancelled:
          type: boolean
          description: False when it was no longer open (e.g. already paid).
          title: Cancelled
        cancel_requested:
          default: false
          description: 'True for a Nequi push the payer can still approve: Nequi cannot withdraw it, so the charge stays pending until it is approved (paid) or expires (failed).'
          type: boolean
          title: Cancel Requested
      required:
      - id
      - status
      - cancelled
      title: ChargeCancellation
    ChargeAmounts:
      type: object
      properties:
        amount_in_cents:
          anyOf:
          - type: integer
          - type: 'null'
          description: The pesos the buyer pays, in cents.
          examples:
          - 15000000
          title: Amount In Cents
      required:
      - amount_in_cents
      title: ChargeAmounts
    ChargeCancellationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ChargeCancellation'
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - 3f9a1c07d2b4
          title: Request Id
      required:
      - data
      title: ChargeCancellationResponse
    CancelBody:
      type: object
      properties:
        reason:
          description: Why, for your records.
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Reason
      additionalProperties: false
      title: CancelBody
    ValidationError:
      type: object
      properties:
        loc:
          type: array
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PublicCustomer:
      type: object
      properties:
        email:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional; the payment processor sends the receipt there.
          title: Email
        full_name:
          anyOf:
          - type: string
          - type: 'null'
          description: Nequi and PSE.
          title: Full Name
        phone_number:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Colombian mobile, 10 digits (+57 accepted): the Nequi to charge; PSE.'
          title: Phone Number
        legal_id_type:
          anyOf:
          - type: string
          - type: 'null'
          description: 'PSE: RC, TI, CC, TE, CE, NIT, PP, DNI, PPT, PA. DaviPlata: CC, CE, TI.'
          title: Legal Id Type
        legal_id:
          anyOf:
          - type: string
          - type: 'null'
          description: PSE and DaviPlata (digits).
          title: Legal Id
        person_type:
          description: 'PSE: `juridica` pays with its NIT.'
          anyOf:
          - type: string
            enum:
            - natural
            - juridica
          - type: 'null'
          title: Person Type
      additionalProperties: true
      description: 'The payer as the business knows them: the checkout opens with these filled in.


        Every field is optional and NOT validated beyond its type: an invalid value shows in its field with its error, so

        the buyer fixes it; it never fails the charge. A key this list does not name is accepted, so one an integrator sends today keeps working.'
      title: PublicCustomer
    ChargeTerms:
      type: object
      properties:
        privacy_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Privacy Url
        personal_auth_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Personal Auth Url
      required:
      - privacy_url
      - personal_auth_url
      title: ChargeTerms
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key