Onboarding Service

Manages the business account onboarding lifecycle for the Kulpay Collection API. Businesses must complete onboarding — including providing bank details, tax information, business details, and a person of contact — before they can create collection requests and receive payments.

Get Account

GET /v1/account

Retrieves the current business account details, including onboarding status, validation errors, and all submitted information.

Response:

{
  "object": "account",
  "id": "acc_mz12345",
  "name": "Pagamentos Rapidos Lda",
  "status": "active",
  "reason": "",
  "details": {
    "bank_details": {
      "nuib": "000100002345678",
      "nib": "000100000012345678910",
      "account_number": "12345678910",
      "bank_name": "BCI - Banco Comercial e de Investimentos",
      "account_holder_name": "Pagamentos Rapidos Lda"
    },
    "person_of_contact": {
      "first_name": "Carlos",
      "last_name": "Mondlane",
      "phone_number": "+258840000000",
      "email": "carlos.mondlane@pagamentosrapidos.co.mz"
    },
    "tax_details": {
      "tax_id": "400012345",
      "vat_number": "MZ400012345"
    },
    "business_details": {
      "legal_name": "Pagamentos Rapidos Lda",
      "short_name": "PagRapidos",
      "country": "MZ",
      "state_province": "Maputo",
      "city": "Maputo",
      "line": "Av. 25 de Setembro, Nr. 1230, 3 Andar",
      "registration_number": "REG-MZ-2024-00789",
      "vat_number": "MZ400012345"
    }
  },
  "errors": [],
  "logo": {
    "file_id": "file_logo_abc123",
    "bucket": "account-logos"
  }
}

When the account has validation issues, the errors array contains details:

{
  "errors": [
    {
      "field": "bank_details.nib",
      "message": "Invalid NIB format",
      "code": "INVALID_FORMAT"
    },
    {
      "field": "business_details.registration_number",
      "message": "Registration number not found in registry",
      "code": "NOT_FOUND"
    }
  ]
}

Approve Account

POST /v1/accounts/{account_id}/approve

Approves a business account that is pending review. Once approved, the account status transitions to active and the business can begin creating collection requests.

Path Parameters:

Parameter	Type	Description
`account_id`	string	The unique account identifier

Response:

{
  "object": "account",
  "id": "acc_mz12345",
  "name": "Pagamentos Rapidos Lda",
  "status": "active",
  "reason": "",
  "details": {
    "bank_details": {
      "nuib": "000100002345678",
      "nib": "000100000012345678910",
      "account_number": "12345678910",
      "bank_name": "BCI - Banco Comercial e de Investimentos",
      "account_holder_name": "Pagamentos Rapidos Lda"
    },
    "person_of_contact": {
      "first_name": "Carlos",
      "last_name": "Mondlane",
      "phone_number": "+258840000000",
      "email": "carlos.mondlane@pagamentosrapidos.co.mz"
    },
    "tax_details": {
      "tax_id": "400012345",
      "vat_number": "MZ400012345"
    },
    "business_details": {
      "legal_name": "Pagamentos Rapidos Lda",
      "short_name": "PagRapidos",
      "country": "MZ",
      "state_province": "Maputo",
      "city": "Maputo",
      "line": "Av. 25 de Setembro, Nr. 1230, 3 Andar",
      "registration_number": "REG-MZ-2024-00789",
      "vat_number": "MZ400012345"
    }
  },
  "errors": [],
  "logo": {
    "file_id": "file_logo_abc123",
    "bucket": "account-logos"
  }
}

Reject Account

POST /v1/accounts/{account_id}/reject

Rejects a business account. The reason field in the response will contain the rejection reason.

Path Parameters:

Parameter	Type	Description
`account_id`	string	The unique account identifier

Response:

{
  "object": "account",
  "id": "acc_mz67890",
  "name": "Comercio Digital Mocambique Lda",
  "status": "rejected",
  "reason": "Bank details could not be verified with BCI. Please confirm your NIB and account number.",
  "details": {
    "bank_details": {
      "nuib": "000200003456789",
      "nib": "000200000098765432100",
      "account_number": "98765432100",
      "bank_name": "Standard Bank Mozambique",
      "account_holder_name": "Comercio Digital Mocambique Lda"
    },
    "person_of_contact": {
      "first_name": "Ana",
      "last_name": "Machel",
      "phone_number": "+258850000000",
      "email": "ana.machel@comerciodigital.co.mz"
    },
    "tax_details": {
      "tax_id": "400098765",
      "vat_number": "MZ400098765"
    },
    "business_details": {
      "legal_name": "Comercio Digital Mocambique Lda",
      "short_name": "ComDigital",
      "country": "MZ",
      "state_province": "Maputo",
      "city": "Matola",
      "line": "Rua da Resistencia, Nr. 45",
      "registration_number": "REG-MZ-2023-01456",
      "vat_number": "MZ400098765"
    }
  },
  "errors": [
    {
      "field": "bank_details.nib",
      "message": "NIB could not be verified with the issuing bank",
      "code": "VERIFICATION_FAILED"
    }
  ],
  "logo": {
    "file_id": "file_logo_def456",
    "bucket": "account-logos"
  }
}

Suspend Account

POST /v1/accounts/{account_id}/suspend

Suspends an active business account. Suspended accounts cannot create new collection requests or receive payments until reactivated.

Path Parameters:

Parameter	Type	Description
`account_id`	string	The unique account identifier

Response:

{
  "object": "account",
  "id": "acc_mz12345",
  "name": "Pagamentos Rapidos Lda",
  "status": "suspended",
  "reason": "Account suspended due to compliance review. Please contact support.",
  "details": {
    "bank_details": {
      "nuib": "000100002345678",
      "nib": "000100000012345678910",
      "account_number": "12345678910",
      "bank_name": "BCI - Banco Comercial e de Investimentos",
      "account_holder_name": "Pagamentos Rapidos Lda"
    },
    "person_of_contact": {
      "first_name": "Carlos",
      "last_name": "Mondlane",
      "phone_number": "+258840000000",
      "email": "carlos.mondlane@pagamentosrapidos.co.mz"
    },
    "tax_details": {
      "tax_id": "400012345",
      "vat_number": "MZ400012345"
    },
    "business_details": {
      "legal_name": "Pagamentos Rapidos Lda",
      "short_name": "PagRapidos",
      "country": "MZ",
      "state_province": "Maputo",
      "city": "Maputo",
      "line": "Av. 25 de Setembro, Nr. 1230, 3 Andar",
      "registration_number": "REG-MZ-2024-00789",
      "vat_number": "MZ400012345"
    }
  },
  "errors": [],
  "logo": {
    "file_id": "file_logo_abc123",
    "bucket": "account-logos"
  }
}

Get Onboarding Status

GET /v1/account/onboarding

Retrieves the current onboarding status for the authenticated business account.

Response:

{
  "status": "pending_review",
  "reason": ""
}

Field	Type	Description
`status`	string	Current onboarding status (see Account Status Values)
`reason`	string	Explanation when status is `rejected` or `suspended`; empty otherwise

Get Onboarding Details

GET /v1/account/onboarding/details

Retrieves the full onboarding details submitted by the business, including bank details, person of contact, and business information.

Response:

{
  "object": "onboarding",
  "bank_details": {
    "nuib": "000100002345678",
    "nib": "000100000012345678910",
    "account_number": "12345678910",
    "bank_name": "BCI - Banco Comercial e de Investimentos",
    "account_holder_name": "Pagamentos Rapidos Lda"
  },
  "person_of_contact": {
    "first_name": "Carlos",
    "last_name": "Mondlane",
    "phone_number": "+258840000000",
    "email": "carlos.mondlane@pagamentosrapidos.co.mz"
  },
  "business_details": {
    "legal_name": "Pagamentos Rapidos Lda",
    "short_name": "PagRapidos",
    "country": "MZ",
    "state_province": "Maputo",
    "city": "Maputo",
    "line": "Av. 25 de Setembro, Nr. 1230, 3 Andar",
    "registration_number": "REG-MZ-2024-00789",
    "vat_number": "MZ400012345"
  }
}

Update Onboarding Details

PUT /v1/account/onboarding/details

Updates the onboarding details for the business account. All sections (bank details, person of contact, and business details) must be provided in full.

Request Body:

{
  "object": "account",
  "bank_details": {
    "nuib": "000300004567890",
    "nib": "000300000056789012345",
    "account_number": "56789012345",
    "bank_name": "Millennium BIM",
    "account_holder_name": "Solucoes Financeiras Lda"
  },
  "person_of_contact": {
    "first_name": "Joana",
    "last_name": "Tembe",
    "phone_number": "+258860000000",
    "email": "joana.tembe@solucoesfinanceiras.co.mz"
  },
  "business_details": {
    "legal_name": "Solucoes Financeiras Lda",
    "short_name": "SolFin",
    "country": "MZ",
    "state_province": "Maputo",
    "city": "Maputo",
    "line": "Av. Eduardo Mondlane, Nr. 567",
    "registration_number": "REG-MZ-2024-02345",
    "vat_number": "MZ400054321"
  }
}

Field	Type	Required	Description
`object`	string	Yes	Always `"account"`
`bank_details`	object	Yes	Bank account information (see BankDetails)
`person_of_contact`	object	Yes	Primary contact person (see Contacts)
`business_details`	object	Yes	Business registration and address (see BusinessDetails)

BankDetails Fields:

Field	Type	Required	Description
`nuib`	string	Yes	Numero Unico de Identificacao Bancaria
`nib`	string	Yes	Numero de Identificacao Bancaria
`account_number`	string	Yes	Bank account number
`bank_name`	string	Yes	Name of the bank (e.g., `BCI`, `Standard Bank`, `Millennium BIM`)
`account_holder_name`	string	Yes	Legal name on the bank account

Person of Contact Fields:

Field	Type	Required	Description
`first_name`	string	Yes	Contact's first name
`last_name`	string	Yes	Contact's last name
`phone_number`	string	No	Contact phone number in E.164 format
`email`	string	No	Contact email address

Business Details Fields:

Field	Type	Required	Description
`legal_name`	string	Yes	Registered legal name of the business
`short_name`	string	No	Short or trading name
`country`	string	Yes	ISO 3166-1 alpha-2 country code (e.g., `MZ`)
`state_province`	string	Yes	State or province (e.g., `Maputo`, `Sofala`, `Nampula`)
`city`	string	No	City name
`line`	string	No	Street address line
`registration_number`	string	Yes	Business registration number
`vat_number`	string	Yes	VAT registration number

Response:

{
  "object": "onboarding",
  "bank_details": {
    "nuib": "000300004567890",
    "nib": "000300000056789012345",
    "account_number": "56789012345",
    "bank_name": "Millennium BIM",
    "account_holder_name": "Solucoes Financeiras Lda"
  },
  "person_of_contact": {
    "first_name": "Joana",
    "last_name": "Tembe",
    "phone_number": "+258860000000",
    "email": "joana.tembe@solucoesfinanceiras.co.mz"
  },
  "business_details": {
    "legal_name": "Solucoes Financeiras Lda",
    "short_name": "SolFin",
    "country": "MZ",
    "state_province": "Maputo",
    "city": "Maputo",
    "line": "Av. Eduardo Mondlane, Nr. 567",
    "registration_number": "REG-MZ-2024-02345",
    "vat_number": "MZ400054321"
  }
}

Initialize Onboarding

POST /v1/account/onboarding/initialize

Initializes the onboarding process for a new business account. This must be called before submitting any onboarding details. No request body is required.

Response:

Returns an empty response with HTTP status 200 OK.

Finish Onboarding

POST /v1/account/onboarding/finish

Submits the completed onboarding for review. All required details (bank details, person of contact, and business details) must be provided before calling this endpoint. The account status transitions to pending_review. No request body is required.

Response:

{
  "object": "account",
  "id": "acc_mz12345",
  "name": "Pagamentos Rapidos Lda",
  "status": "pending_review",
  "reason": "",
  "details": {
    "bank_details": {
      "nuib": "000100002345678",
      "nib": "000100000012345678910",
      "account_number": "12345678910",
      "bank_name": "BCI - Banco Comercial e de Investimentos",
      "account_holder_name": "Pagamentos Rapidos Lda"
    },
    "person_of_contact": {
      "first_name": "Carlos",
      "last_name": "Mondlane",
      "phone_number": "+258840000000",
      "email": "carlos.mondlane@pagamentosrapidos.co.mz"
    },
    "tax_details": {
      "tax_id": "400012345",
      "vat_number": "MZ400012345"
    },
    "business_details": {
      "legal_name": "Pagamentos Rapidos Lda",
      "short_name": "PagRapidos",
      "country": "MZ",
      "state_province": "Maputo",
      "city": "Maputo",
      "line": "Av. 25 de Setembro, Nr. 1230, 3 Andar",
      "registration_number": "REG-MZ-2024-00789",
      "vat_number": "MZ400012345"
    }
  },
  "errors": [],
  "logo": {
    "file_id": "file_logo_abc123",
    "bucket": "account-logos"
  }
}

Upload File

POST /v1/files

Uploads a file to the system. Used for uploading account logos, supporting documents, and other files associated with the onboarding process.

Request Body:

Field	Type	Required	Description
`file`	bytes	Yes	The file content to upload
`file_type`	string	Yes	File extension (e.g., `png`, `jpg`, `pdf`)

Response:

{
  "object": "uploaded_file",
  "id": "file_abc12345",
  "file_type": "png",
  "file_size": 245760,
  "file": {
    "file_id": "file_abc12345",
    "bucket": "account-logos"
  }
}

Field	Type	Description
`object`	string	Always `"uploaded_file"`
`id`	string	Unique file identifier
`file_type`	string	File extension
`file_size`	integer	File size in bytes
`file.file_id`	string	File identifier for referencing in other API calls
`file.bucket`	string	Storage bucket where the file is stored

Data Models

Account Status Values

Status	Description
`pending`	Account created, awaiting onboarding completion
`pending_review`	Onboarding submitted, awaiting approval
`active`	Account approved and operational
`rejected`	Account rejected (reason provided in the `reason` field)
`suspended`	Account suspended (reason provided in the `reason` field)

Validation Errors

When an account has issues that need to be resolved, the errors array in the AccountResponse contains one or more ValidationError objects:

Field	Type	Description
`field`	string	Dot-notation path to the invalid field (e.g., `bank_details.nib`)
`message`	string	Human-readable description of the error
`code`	string	Machine-readable error code (e.g., `INVALID_FORMAT`, `NOT_FOUND`, `VERIFICATION_FAILED`)

{
  "field": "bank_details.nib",
  "message": "Invalid NIB format",
  "code": "INVALID_FORMAT"
}

BankDetails

Field	Type	Required	Description
`nuib`	string	Yes	Numero Unico de Identificacao Bancaria
`nib`	string	Yes	Numero de Identificacao Bancaria
`account_number`	string	Yes	Bank account number
`bank_name`	string	Yes	Name of the issuing bank (e.g., `BCI - Banco Comercial e de Investimentos`, `Standard Bank Mozambique`, `Millennium BIM`, `Absa Mozambique`)
`account_holder_name`	string	Yes	Legal name registered on the bank account

Contacts (Person of Contact)

Field	Type	Required	Description
`first_name`	string	Yes	Contact's first name
`last_name`	string	Yes	Contact's last name
`phone_number`	string	No	Phone number in E.164 format (e.g., `+258840000000`)
`email`	string	No	Contact email address

TaxDetails

Field	Type	Required	Description
`tax_id`	string	Yes	Tax identification number (NUIT)
`vat_number`	string	Yes	VAT registration number (e.g., `MZ400012345`)

BusinessDetails

Field	Type	Required	Description
`legal_name`	string	Yes	Registered legal name of the business
`short_name`	string	No	Short or trading name
`country`	string	Yes	ISO 3166-1 alpha-2 country code (e.g., `MZ`)
`state_province`	string	Yes	State or province (e.g., `Maputo`, `Gaza`, `Sofala`, `Nampula`)
`city`	string	No	City name (e.g., `Maputo`, `Matola`, `Beira`, `Nampula`)
`line`	string	No	Street address line (e.g., `Av. 25 de Setembro, Nr. 1230, 3 Andar`)
`registration_number`	string	Yes	Business registration number issued by the registry
`vat_number`	string	Yes	VAT registration number

Get Account​

Approve Account​

Reject Account​

Suspend Account​

Get Onboarding Status​

Get Onboarding Details​

Update Onboarding Details​

Initialize Onboarding​

Finish Onboarding​

Upload File​

Data Models​

Account Status Values​

Validation Errors​

BankDetails​

Contacts (Person of Contact)​

TaxDetails​

BusinessDetails​

Get Account

Approve Account

Reject Account

Suspend Account

Get Onboarding Status

Get Onboarding Details

Update Onboarding Details

Initialize Onboarding

Finish Onboarding

Upload File

Data Models

Account Status Values

Validation Errors

BankDetails

Contacts (Person of Contact)

TaxDetails

BusinessDetails