Working with invoices

An invoice can be created with payer details (address, phone, name) or without them. In the first case, the resident will see the invoice in the mobile app and can pay directly from there. In the second case, the invoice can only be paid via a link. The invoice can also be directly linked to a user. This is convenient to do, for example, from a mini-app. In this case, the resident will also see the invoice in the mobile app.

Anonymous Invoice

The minimum set of fields required to create an invoice creates an anonymous invoice. Such an invoice is not visible in the mobile app and can only be paid via a link.
  • dv
  • sender
  • organization - the organization creating the invoice
  • toPay - Total amount of the invoice
  • rows - Items included in the invoice (services/products). This is an array of objects like:
json
{ "name": "Service 1", "count": 1, "toPay": "100", "isMin": false }
The isMin field indicates that toPay is the minimum price (price from). It is set to false after the final price is agreed upon.
  • paymentType - Payment type. Possible values: online and cash. This field is more informational. You can always generate a payment link and still pay in cash.
  • status
This is the invoice status. Possible values: draft, published, paid, canceled. A draft cannot be paid and cannot be viewed in the mobile app. A published invoice cannot be edited, nor can an already paid invoice.
graphql
mutation createInvoice {
  obj: createInvoice(
    data: {
      dv: 1,
      sender: { dv: 1, fingerprint: "playground" },
      organization: {connect: {id: "e40b5367-49a8-4340-9eed-802538331326"}},
      toPay: "100",
      rows: [{name: "Service 1", count: 1, toPay: "100", isMin: false}],
      paymentType: "online", status: "draft"
    }
  ) {
    id
    number
    status
    organization {
      id
      name
    }
    property {
      id
      address
    }
    unitName
    unitType
    toPay
    rows {
      name
      toPay
      count
      isMin
      currencyCode
      sku
    }
    createdAt
    updatedAt
    createdBy {
      id
    }
    updatedBy {
      id
    }
    deletedAt
    publishedAt
    paidAt
  }
}

Invoice for Resident

To make the invoice visible in the mobile app, the payer's address must be specified. These are the fields property, unitType, and unitName. If available, the resident's name and phone number can be provided in the clientName and clientPhone fields. In this case, the resident’s contact (the contact field in the server's response) will be linked to the invoice. If such a contact already exists, it will be linked. If no such contact exists, it will be created and linked to the invoice.
graphql
mutation createInvoice {
  obj: createInvoice(
    data: {
      dv: 1,
      sender: {dv: 1, fingerprint: "docs-demo"},
      organization: {connect: {id: "e40b5367-49a8-4340-9eed-802538331326"}},
      property: {connect: {id: "809bff2d-b1ff-485e-b2e9-33b4c5974d3b"}},
      unitName: "3",
      unitType: flat,
      clientPhone: "+79999999997",
      clientName: "Pushkin",
      toPay: "200",
      rows: [{name: "test row", count: 1, toPay: "200", isMin: false}],
      paymentType: online,
      status: draft}
  ) {
    id
    number
    status
    contact {
      id
      name
      phone
      property {
        id
        address
      }
      unitType
      unitName
    }
    organization {
      id
      name
    }
    property {
      id
      address
    }
    unitName
    unitType
    toPay
    rows {
      name
      toPay
      count
      isMin
      currencyCode
      sku
    }
    createdAt
    updatedAt
    createdBy {
      id
    }
    updatedBy {
      id
    }
    deletedAt
    publishedAt
    paidAt
  }
}

Invoice from b2c Mini-App

An invoice can be issued to a resident using the mini-app. The request to create the invoice is sent from the mini-app's backend. For this, the mini-app must be authorized under a service user (see the authentication section).
The service user of the mini-app will have access to create, edit, and read invoices on behalf of the organization (the organization field) once the organization connects the mini-app (b2b part).
The organization specified when creating the invoice in the organization field will see the invoice in the "Marketplace" section. To ensure the resident receives a push notification and sees the new invoice in their mobile app, the following fields must be provided:
  • client - User identifier
  • property - The building the resident is registered in
  • unitType - The type of the resident's unit
  • unitName - The unit name (apartment number)
graphql
mutation createInvoice {
  obj: createInvoice(
    data: {
      dv: 1,
      sender: {dv: 1, fingerprint: "docs-demo"},
      organization: {connect: {id: "73b069e4-d807-4946-8725-88781e5d14ac"}},
      property: {connect: {id: "2c398c8d-da20-4b4f-b8c8-a19df803e21d"}},
      client: {connect: {id: "cf609bd7-5bb8-498d-865d-943f96bf11fc"}},
      unitType: flat,
      unitName: "13",
      rows: [{name: "test row 3", count: 1, toPay: "203", isMin: false}],
      paymentType: online,
      status: published
    }
  ) {
    id
    number
    status
    organization {
      id
      name
    }
    toPay
    rows {
      name
      toPay
      count
      isMin
      currencyCode
      sku
    }
    createdAt
    updatedAt
    createdBy {
      id
    }
    updatedBy {
      id
    }
    deletedAt
    publishedAt
    paidAt
  }
}

Editing the Invoice

To edit an invoice, the standard object update method is used.
Example of modifying the service list:
graphql
mutation updateInvoice {
  obj: updateInvoice(
    id: "34b5c321-c086-4540-bca8-18f23580be7d"
    data: {
      dv: 1,
      sender: {dv: 1, fingerprint: "playground"},
      rows: [{name: "Another service", count: 1, toPay: "100", isMin: false}]
    }
  ) {
    id
    number
    status
    organization {
      id
      name
    }
    property {
      id
      address
    }
    unitName
    unitType
    toPay
    rows {
      name
      toPay
      count
      isMin
      currencyCode
      sku
    }
    createdAt
    updatedAt
    createdBy {
      id
    }
    updatedBy {
      id
    }
    deletedAt
    publishedAt
    paidAt
  }
}

Invoice Publication

After publication, the invoice can be viewed in the mobile app and paid. If the invoice contains items with an implicit price (isMin=true), the invoice cannot be published. Publication is the editing of the invoice, where the status field is changed to published.
The payment link template looks like this:
https://condo.d.doma.ai/payment-link?su={successUrl}&fu={failureUrl}&i={invoiceId}
FieldDescriptionType/FormatExample
successUrlThe address where the user will be redirected after a successful paymentstring, url encodedhttps%3A%2F%2Fcondo.d.doma.ai%2Fsuccess
failureUrlThe address where the user will be redirected if the payment failsstring, url encodedhttps%3A%2F%2Fcondo.d.doma.ai%2Ffailure
invoiceIdThe invoice identifierstring, UUID14d5f5c9-de39-4d02-9116-6a2e501e54e1
When following the link, acquiring entities will be created, and the user will be redirected to a page to enter their bank card details. After payment, the user will be redirected to the result page (success/error).
Edit this page on Github
Back: Preparing
Next: Distribution