Xflow Receivables API

openapi: 3.0.0
info:
  contact:
    email: support@xflowpay.com
    name: Xflow Support
    url: https://xflowpay.com
  description: The Xflow REST API. Please see https://docs.xflowpay.com/2024-02-05/api for more details.
  termsOfService: https://docs.xflowpay.com/platform-agreement
  title: Xflow Accounts Receivables API
  version: '2024-02-05'
servers:
- url: https://api.xflowpay.com/
security:
- bearerAuth: []
tags:
- name: Receivables
paths:
  /v1/receivables:
    get:
      description: Returns a list of receivables.
      operationId: ListReceivables
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - description: Return results where the `created` field is equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.eq
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is greater than the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.gt
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is greater than or equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.gte
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is lesser than the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.lt
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is lesser than or equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.lte
        required: false
        schema:
          format: unix-time
          type: integer
      - description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the currency.
        in: query
        name: currency
        required: false
        schema:
          items:
            type: string
          type: array
      - description: A cursor for use in pagination. `ending_before` is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
        in: query
        name: ending_before
        required: false
        schema:
          type: string
      - description: A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - description: A cursor for use in pagination. `starting_after` is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with `obj_bar`, your subsequent call can include `starting_after=obj_bar` in order to fetch the next page of the list.
        in: query
        name: starting_after
        required: false
        schema:
          type: string
      - description: Valid status for receivables.
        in: query
        name: status
        required: false
        schema:
          items:
            enum:
            - draft
            - verifying
            - activated
            - completed
            - cancelled
            - hold
            - input_required
            type: string
          type: array
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/receivable'
                    type: array
                  has_next:
                    description: True if this list has another page of items after this one that can be fetched.
                    type: boolean
                  object:
                    description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
                    enum:
                    - list
                    type: string
                title: ListReceivablesResponse
                type: object
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Receivables
    post:
      description: Create a receivable.
      operationId: CreateReceivable
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                account_id:
                  description: Unique identifier for the account object of `type=partner`.
                  type: string
                amount_maximum_reconcilable:
                  description: Maximum amount value that can be reconciled. This field can be edited by the user.
                  type: string
                currency:
                  description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
                  enum:
                  - AED
                  - AUD
                  - CHF
                  - CZK
                  - DKK
                  - EUR
                  - GBP
                  - HKD
                  - INR
                  - NOK
                  - PLN
                  - SEK
                  - SGD
                  - USD
                  type: string
                description:
                  description: Represents an array of deposit objects due to which amount is locked.
                  type: string
                hsn_code:
                  description: Harmonized System Nomenclature (HSN) code use to classify the goods for cross-border trade.
                  type: string
                invoice:
                  description: Relationship of the person with the account.
                  properties:
                    amount:
                      description: Total amount value on the invoice.
                      type: string
                    creation_date:
                      description: The date on which the invoice was created in YYYY-MM-DD format.
                      type: string
                    currency:
                      description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
                      type: string
                    document:
                      description: Represents a file object with invoice details.
                      type: string
                    due_date:
                      description: The date on which the invoice amount is due in YYYY-MM-DD format.
                      type: string
                    reference_number:
                      description: Unique identification number on the invoice.
                      type: string
                  title: CreateReceivableRequestInvoice
                  type: object
                metadata:
                  additionalProperties:
                    type: string
                  description: Set of [key-value pairs](https://docs.xflowpay.com/2024-02-05/api#metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
                  title: CreateReceivableRequestMetadata
                  type: object
                purpose_code:
                  description: '[Purpose codes](https://www.rbi.org.in/upload/notification/pdfs/52220.pdf) defined by the Financial Regulator for cross-border transactions.'
                  type: string
                purpose_code_description:
                  description: Description of the purpose code.
                  type: string
                supporting_documentation:
                  description: Details of the supporting documentation.
                  type: object
                  properties:
                    documents:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            description: Internal id associated with the document submission.
                            type: string
                          file_id:
                            description: A file object identifier that references a document validating the transaction made via the receivable.
                            type: string
                          reconcile_id:
                            description: Id of the reconcile event. It is used to associate the document with a specific reconcile action. If not provided, the document is considered to be against the receivable.
                            type: string
                          type:
                            description: Type of document submitted.
                            type: string
                            enum:
                            - customs
                            - shipping
                    status:
                      description: Status of the supporting documentation.
                      type: string
                transaction_type:
                  description: Receivable transaction type.
                  enum:
                  - goods
                  - services
                  - software
                  type: string
              title: CreateReceivableRequest
              type: object
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/receivable'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Receivables
  /v1/receivables/{receivable}:
    get:
      description: Retrieves the details of a receivable.
      operationId: RetrieveReceivable
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - in: path
        name: receivable
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/receivable'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Receivables
    post:
      description: Update the details of a receivable.
      operationId: UpdateReceivable
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - in: path
        name: receivable
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              properties:
                account_id:
                  description: Unique identifier for the account object of `type=partner`.
                  type: string
                amount_maximum_reconcilable:
                  description: Maximum amount value that can be reconciled. This field can be edited by the user.
                  type: string
                currency:
                  description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
                  enum:
                  - AED
                  - AUD
                  - CHF
                  - CZK
                  - DKK
                  - EUR
                  - GBP
                  - HKD
                  - INR
                  - NOK
                  - PLN
                  - SEK
                  - SGD
                  - USD
                  type: string
                description:
                  description: Represents an array of deposit objects due to which amount is locked.
                  type: string
                hsn_code:
                  description: Harmonized System Nomenclature (HSN) code use to classify the goods for cross-border trade.
                  type: string
                invoice:
                  description: Relationship of the person with the account.
                  properties:
                    amount:
                      description: Total amount value on the invoice.
                      type: string
                    creation_date:
                      description: The date on which the invoice was created in YYYY-MM-DD format.
                      type: string
                    currency:
                      description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
                      type: string
                    document:
                      description: Represents a file object with invoice details.
                      type: string
                    due_date:
                      description: The date on which the invoice amount is due in YYYY-MM-DD format.
                      type: string
                    reference_number:
                      description: Unique identification number on the invoice.
                      type: string
                  title: UpdateReceivableRequestInvoice
                  type: object
                metadata:
                  additionalProperties:
                    type: string
                  description: Set of [key-value pairs](https://docs.xflowpay.com/2024-02-05/api#metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
                  title: UpdateReceivableRequestMetadata
                  type: object
                purpose_code:
                  description: '[Purpose codes](https://www.rbi.org.in/upload/notification/pdfs/52220.pdf) defined by the Financial Regulator for cross-border transactions.'
                  type: string
                purpose_code_description:
                  description: Description of the purpose code.
                  type: string
                supporting_documentation:
                  description: Details of the supporting documentation.
                  type: object
                  properties:
                    documents:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            description: Internal id associated with the document submission.
                            type: string
                          file_id:
                            description: A file object identifier that references a document validating the transaction made via the receivable.
                            type: string
                          reconcile_id:
                            description: Id of the reconcile event. It is used to associate the document with a specific reconcile action. If not provided, the document is considered to be against the receivable.
                            type: string
                          type:
                            description: Type of document submitted.
                            type: string
                            enum:
                            - customs
                            - shipping
                    status:
                      description: Status of the supporting documentation.
                      type: string
                transaction_type:
                  description: Receivable transaction type.
                  enum:
                  - goods
                  - services
                  - software
                  type: string
              title: UpdateReceivableRequest
              type: object
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/receivable'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Receivables
  /v1/receivables/{receivable}/confirm:
    post:
      description: Confirm the details of a receivable.
      operationId: ConfirmReceivable
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - in: path
        name: receivable
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/receivable'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Receivables
  /v1/receivables/{receivable}/cancel:
    post:
      description: Cancel a receivable.
      operationId: CancelReceivable
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - in: path
        name: receivable
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/receivable'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Receivables
  /v1/receivables/{receivable}/reconcile:
    post:
      description: Reconcile a receivable.
      operationId: ReconcileReceivable
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - in: path
        name: receivable
        required: true
        schema:
          type: string
        style: simple
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/receivable'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Receivables
components:
  schemas:
    receivable:
      description: The receivable object represents an intent expressed by the user to accept funds from their partners. Typically, this intent is expressed by providing an underlying invoice for the desired inflow of funds.
      properties:
        account_id:
          description: Unique identifier for the account object of `type=partner`.
          nullable: true
          type: string
        amount_locked:
          description: Amount value that is unavailable for reconciliation because XFlow is processing a payment of an equivalent amount. The value includes locks linked to payments being processed by XFlow and XFlow’s partner providers like PayPal. Locked value associated with XFlow-processed payments can be identified through the field `deposit_ids_amount_locked`.
          nullable: true
          type: string
        amount_maximum_reconcilable:
          description: Maximum amount value that can be reconciled. This field can be edited by the user.
          nullable: true
          type: string
        amount_reconcilable:
          description: Amount value that is available for reconciliation. This field is a calculated field and is returned by Xflow. The formula to calculate this value is `amount_reconcilable` = `amount_maximum_reconcilable` - (`amount_locked` + `amount_reconciled`)
          nullable: true
          type: string
        amount_reconciled:
          description: Amount value that has been reconciled. This is a calculated field and is returned by XFlow. The value is inclusive of reconciliations linked to payments that have been or will be settled by XFlow, and XFlow’s partner providers like PayPal. Reconciled value for payments settled by XFlow can be calculated as `amount_reconciled_not_settled` + `amount_settled_payouts` + fees. Reconciled value linked to payments settled by other providers can be calculated as `amount_reconciled` - `amount_reconciled_not_settled` - `amount_settled_payouts` - fees.
          nullable: true
          type: string
        amount_reconciled_not_settled:
          description: Amount value that has been reconciled but not paid out. This is a calculated field and is returned by Xflow.
          nullable: true
          type: string
        amount_settled_payouts:
          description: Amount value that has been transferred for payout. This is a calculated field and is returned by Xflow.
          nullable: true
          type: string
        created:
          description: The seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) at which the receivable object was created.
          format: unix-time
          type: integer
        currency:
          description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
          enum:
          - AED
          - AUD
          - CHF
          - CZK
          - DKK
          - EUR
          - GBP
          - HKD
          - INR
          - NOK
          - PLN
          - SEK
          - SGD
          - USD
          nullable: true
          type: string
        deposit_ids_amount_locked:
          description: Represents an array of deposit objects due to which amount is locked.
          items:
            type: string
          nullable: true
          type: array
        description:
          description: Represents an array of deposit objects due to which amount is locked.
          nullable: true
          type: string
        hsn_code:
          description: Harmonized System Nomenclature (HSN) code use to classify the goods for cross-border trade.
          nullable: true
          type: string
        id:
          description: Unique identifier for the object.
          type: string
        invoice:
          description: Relationship of the person with the account.
          properties:
            amount:
              description: Total amount value on the invoice.
              nullable: true
              type: string
            creation_date:
              description: The date on which the invoice was created in YYYY-MM-DD format.
              nullable: true
              type: string
            currency:
              description: Th

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xflow/refs/heads/main/openapi/xflow-receivables-api-openapi.yml