Collection Method Service

Manages collection methods that define how payments can be collected for invoices. Collection methods configure the payment channels (SIMO ERV or interbank) and banking details used to receive payments.

Create Collection Method

POST /v1/collection-methods

Creates a new collection method for receiving payments.

Request Body:

{
  "name": "EDM Pagamentos SIMO",
  "type": "simo_erv",
  "details": {
    "entity_number": "17890",
    "allow_installments": true,
    "allow_reuses": false,
    "nib": "000100000345678901048"
  }
}

Field	Type	Required	Description
name	string	Yes	Collection method name
type	string	Yes	Collection method type (simo_erv or interbank)
details	object	Yes	Configuration details for the collection method
details.entity_number	string	Yes	Entity number used to identify the collecting organization
details.allow_installments	boolean	No	Whether installment payments are accepted
details.allow_reuses	boolean	No	Whether the collection method can be reused across multiple invoices
details.nib	string	No	Bank identification number (Numero de Identificacao Bancaria)

Response:

{
  "object": "collection_method",
  "id": "cm_abc12345",
  "name": "EDM Pagamentos SIMO",
  "type": "simo_erv",
  "details": {
    "entity_number": "17890",
    "allow_installments": true,
    "allow_reuses": false,
    "nib": "000100000345678901048"
  },
  "created_at": "2025-09-01T08:30:00Z",
  "updated_at": "2025-09-01T08:30:00Z"
}

---

Get Collection Method

GET /v1/collection-methods/{id}

Retrieves a single collection method by its ID.

Path Parameters:

Parameter	Type	Description
id	string	Collection method ID

Query Parameters:

Parameter	Type	Required	Description
account_id	string	Yes	Account ID that owns the collection method

Response:

{
  "object": "collection_method",
  "collection_method": {
    "id": "cm_abc12345",
    "name": "EDM Pagamentos SIMO",
    "type": "simo_erv",
    "account_id": "acc_mz98765",
    "details": {
      "entity_number": "17890",
      "allow_installments": true,
      "allow_reuses": false,
      "nib": "000100000345678901048"
    },
    "created_at": "2025-09-01T08:30:00Z",
    "updated_at": "2025-09-01T08:30:00Z"
  },
  "error": null
}

---

List Collection Methods

GET /v1/collection-methods

Retrieves a paginated list of collection methods.

Query Parameters:

Parameter	Type	Required	Default	Description
account_id	string	No	-	Filter by account ID
page_size	integer	No	50	Max results per page (max: 100)
created_at	timestamp	No	-	Filter collection methods created from this date
created_at2	timestamp	No	-	Filter collection methods created up to this date
limit	integer	No	-	Maximum number of results to return

Response:

{
  "object": "list",
  "items": [
    {
      "id": "cm_abc12345",
      "name": "EDM Pagamentos SIMO",
      "type": "simo_erv",
      "account_id": "acc_mz98765",
      "details": {
        "entity_number": "17890",
        "allow_installments": true,
        "allow_reuses": false,
        "nib": null
      },
      "created_at": "2025-09-01T08:30:00Z",
      "updated_at": "2025-09-01T08:30:00Z"
    },
    {
      "id": "cm_def67890",
      "name": "Transferencia Interbancaria BCI",
      "type": "interbank",
      "account_id": "acc_mz98765",
      "details": {
        "entity_number": "22450",
        "allow_installments": false,
        "allow_reuses": true,
        "nib": "000400001234567890132"
      },
      "created_at": "2025-08-15T14:00:00Z",
      "updated_at": "2025-08-20T09:45:00Z"
    }
  ],
  "has_more": false,
  "next_page_token": null,
  "error": null
}

---

Update Collection Method

PUT /v1/collection-methods

Updates an existing collection method.

Request Body:

{
  "id": "cm_abc12345",
  "name": "EDM Pagamentos SIMO Atualizado",
  "type": "simo_erv",
  "account_id": "acc_mz98765",
  "entity_number": "17890",
  "nib": "000100000345678901048",
  "allow_installments": true,
  "allow_reuses": true
}

Field	Type	Required	Description
id	string	Yes	Collection method ID to update
name	string	Yes	Updated collection method name
type	string	No	Collection method type (simo_erv or interbank)
account_id	string	Yes	Account ID that owns the collection method
entity_number	string	No	Updated entity number
nib	string	No	Updated bank identification number
allow_installments	boolean	No	Whether installment payments are accepted
allow_reuses	boolean	No	Whether the collection method can be reused

Response:

{
  "object": "collection_method",
  "collection_method": {
    "id": "cm_abc12345",
    "name": "EDM Pagamentos SIMO Atualizado",
    "type": "simo_erv",
    "account_id": "acc_mz98765",
    "details": {
      "entity_number": "17890",
      "allow_installments": true,
      "allow_reuses": true,
      "nib": "000100000345678901048"
    },
    "created_at": "2025-09-01T08:30:00Z",
    "updated_at": "2025-09-10T11:15:00Z"
  },
  "error": null
}

---

Delete Collection Method

DELETE /v1/collection-methods

Deletes a collection method.

Query Parameters:

Parameter	Type	Required	Description
id	string	Yes	Collection method ID to delete
account_id	string	Yes	Account ID that owns the collection method

Response:

{
  "object": "collection_method",
  "error": null
}

---

Collection Method Types

Type	Description
simo_erv	SIMO ERV (Sistema Interbancario de Mocambique - Entidade Referencia Virtual). Uses entity number and reference number for payment identification.
interbank	Interbank transfer. Uses NIB (Numero de Identificacao Bancaria) for direct bank-to-bank transfers.