Payment Service

Manages payment records for collection requests. Supports creating, listing, ingesting external payments, and managing payment lifecycle.

Create Payment

POST /v1/payments

Creates a new payment record associated with a collection request.

Request Body:

{
  "account_id": "acc_mz12345",
  "collection_request_id": "cr_abc12345",
  "provider_id": "provider_mpesa",
  "channel": "mobile_wallet",
  "currency": "MZN",
  "amount": 7500.00,
  "status": "pending"
}

Field	Type	Required	Description
`account_id`	string	Yes	Account making the payment
`collection_request_id`	string	No	Associated collection request ID
`provider_id`	string	No	Payment provider identifier
`channel`	string	No	Payment channel (e.g., `mobile_wallet`, `bank_transfer`)
`currency`	string	Yes	ISO 4217 currency code (e.g., `MZN`)
`amount`	double	Yes	Payment amount
`status`	string	Yes	Payment status: `pending`, `failed`, or `confirmed`

Response:

{
  "object": "payment",
  "payment": {
    "id": "pm_abc12345",
    "account_id": "acc_mz12345",
    "collection_request_id": "cr_abc12345",
    "provider_id": "provider_mpesa",
    "channel": "mobile_wallet",
    "amount": {
      "currency": "MZN",
      "value": 7500.00
    },
    "status": "pending",
    "processed_at": null,
    "confirmed_at": null,
    "created_at": "2025-07-10T08:30:00Z",
    "deleted_at": null
  },
  "error": null
}

List Payments

GET /v1/payments

Retrieves a paginated list of payments with optional filters.

Query Parameters:

Parameter	Type	Default	Description
`collection_request_id`	string	-	Filter by collection request ID
`status`	string	-	Filter by status: `pending`, `failed`, or `confirmed`
`channel`	string	-	Filter by payment channel
`provider_id`	string	-	Filter by provider ID
`amount_min`	double	-	Minimum payment amount
`amount_max`	double	-	Maximum payment amount
`from`	string	-	Date range start (ISO 8601 timestamp)
`to`	string	-	Date range end (ISO 8601 timestamp)
`currency`	string	-	Filter by ISO currency code
`page_size`	integer	50	Max results per page (max: 100)
`page_token`	string	-	Token for next page

Response:

{
  "object": "list",
  "items": [
    {
      "id": "pm_abc12345",
      "account_id": "acc_mz12345",
      "collection_request_id": "cr_abc12345",
      "provider_id": "provider_mpesa",
      "channel": "mobile_wallet",
      "amount": {
        "currency": "MZN",
        "value": 7500.00
      },
      "status": "confirmed",
      "processed_at": "2025-07-10T08:31:00Z",
      "confirmed_at": "2025-07-10T08:31:05Z",
      "created_at": "2025-07-10T08:30:00Z",
      "deleted_at": null
    },
    {
      "id": "pm_def67890",
      "account_id": "acc_mz67890",
      "collection_request_id": "cr_def67890",
      "provider_id": "provider_emola",
      "channel": "mobile_wallet",
      "amount": {
        "currency": "MZN",
        "value": 3200.50
      },
      "status": "pending",
      "processed_at": null,
      "confirmed_at": null,
      "created_at": "2025-07-10T09:15:00Z",
      "deleted_at": null
    }
  ],
  "has_more": true,
  "next_page_token": "token_xyz789",
  "error": null
}

Ingest Payment

POST /v1/payments/ingest

Imports and reconciles an external payment into the system. Used for ingesting payments from external sources such as banks or payment gateways.

Request Body:

{
  "id": "ext_pay_20250710_001",
  "amount": 15000.00,
  "currency": "MZN",
  "status": "completed",
  "payment_method_type": "SIMO_ERV",
  "payment_method_details": {
    "nib": "000100000012345678910",
    "entity_number": "12345",
    "reference_number": "REF-MZ-2025-00456"
  },
  "reference": "BCI-TRF-20250710-001",
  "source": "Bank",
  "processed_at": "2025-07-10T10:00:00Z"
}

Field	Type	Required	Description
`id`	string	Yes	External payment ID from the source system
`amount`	double	Yes	Payment amount
`currency`	string	Yes	ISO 4217 currency code (e.g., `MZN`)
`status`	string	Yes	Payment status: `pending`, `completed`, or `failed`
`payment_method_type`	string	No	Payment method type (e.g., `SIMO_ERV`, `INTERBANK`)
`payment_method_details`	object	Yes	Payment method details (see below)
`reference`	string	No	External reference identifier
`source`	string	Yes	Source of the payment (e.g., `Bank`, `Payment Gateway`)
`processed_at`	string	Yes	Timestamp when the payment was processed (ISO 8601)

Payment Method Details:

Field	Type	Description
`nib`	string	Bank account NIB (Numero de Identificacao Bancaria)
`entity_number`	string	Entity number for the payment
`reference_number`	string	Reference number for the transaction

Response:

{
  "object": "payment_ingest",
  "ingest_payment": {
    "id": "ext_pay_20250710_001",
    "amount": 15000.00,
    "currency": "MZN",
    "status": "completed",
    "payment_method_type": "SIMO_ERV",
    "payment_method_details": {
      "nib": "000100000012345678910",
      "entity_number": "12345",
      "reference_number": "REF-MZ-2025-00456"
    },
    "reference": "BCI-TRF-20250710-001",
    "source": "Bank",
    "processed_at": "2025-07-10T10:00:00Z",
    "updated_at": "2025-07-10T10:00:05Z",
    "created_at": "2025-07-10T10:00:05Z",
    "deleted_at": null
  },
  "error": null
}

Get Payment

GET /v1/payments/{id}

Retrieves details of a specific payment by ID.

Path Parameters:

Parameter	Type	Description
`id`	string	Payment ID

Response:

{
  "object": "payment",
  "payment": {
    "id": "pm_abc12345",
    "account_id": "acc_mz12345",
    "collection_request_id": "cr_abc12345",
    "provider_id": "provider_mpesa",
    "channel": "mobile_wallet",
    "amount": {
      "currency": "MZN",
      "value": 7500.00
    },
    "status": "confirmed",
    "processed_at": "2025-07-10T08:31:00Z",
    "confirmed_at": "2025-07-10T08:31:05Z",
    "created_at": "2025-07-10T08:30:00Z",
    "deleted_at": null
  },
  "error": null
}

Update Payment

PUT /v1/payments/{id}

Updates an existing payment record. Only provided fields are updated.

Path Parameters:

Parameter	Type	Description
`id`	string	Payment ID

Request Body:

{
  "account_id": "acc_mz12345",
  "collection_request_id": "cr_abc12345",
  "provider_id": "provider_emola",
  "channel": "bank_transfer",
  "amount": 8000.00,
  "currency": "MZN",
  "status": "confirmed"
}

Field	Type	Required	Description
`account_id`	string	Yes	Account making the payment
`collection_request_id`	string	No	Associated collection request ID
`provider_id`	string	No	Payment provider identifier
`channel`	string	No	Payment channel
`amount`	double	No	Updated payment amount
`currency`	string	No	ISO 4217 currency code
`status`	string	No	Updated payment status

Response:

{
  "object": "payment",
  "payment": {
    "id": "pm_abc12345",
    "account_id": "acc_mz12345",
    "collection_request_id": "cr_abc12345",
    "provider_id": "provider_emola",
    "channel": "bank_transfer",
    "amount": {
      "currency": "MZN",
      "value": 8000.00
    },
    "status": "confirmed",
    "processed_at": "2025-07-10T08:31:00Z",
    "confirmed_at": "2025-07-10T08:35:00Z",
    "created_at": "2025-07-10T08:30:00Z",
    "deleted_at": null
  },
  "error": null
}

Delete Payment

DELETE /v1/payments/{id}

Deletes a payment record from the system.

Path Parameters:

Parameter	Type	Description
`id`	string	Payment ID (pattern: `^pm_[a-zA-Z0-9]+$`)

Response:

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

Payment Status Values

Status	Description
`pending`	Payment created, awaiting processing
`confirmed`	Payment successfully processed
`failed`	Payment processing failed

Create Payment​

List Payments​

Ingest Payment​

Get Payment​

Update Payment​

Delete Payment​

Payment Status Values​

Create Payment

List Payments

Ingest Payment

Get Payment

Update Payment

Delete Payment

Payment Status Values