> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexapay.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate Cross-Border Collection

> Starts a cross-border collection. For Kenya, this sends an M-Pesa collection request. For Uganda, this sends an MTN mobile money collection request. NexaPay locks the merchant NGN amount for instant credit after successful provider confirmation.

Starts a cross-border payment collection request for a supported corridor.

For Kenya, this initiates an M-Pesa collection request to the customer's phone number. For Uganda, this initiates an MTN mobile money collection request. The merchant is credited in NGN after the provider confirms successful payment.

### Notes

* Send customer-facing amounts in normal source-currency units, such as `100` for `100 KES`.
* The NGN amount and exchange rate are locked at initiation.
* The initial transaction status is usually `PROCESSING`.
* On successful provider confirmation, the merchant's NGN balance is credited instantly and the transaction becomes `COMPLETED`.
* Use `merchantReference` to map the collection back to your order, invoice, or checkout session.

### Uganda Example

```json theme={null}
{
  "businessId": "69e698368d883f70f4d4ed21",
  "country": "UG",
  "currency": "UGX",
  "amount": 20000,
  "paymentMethod": "MTN",
  "merchantReference": "ORDER-UG-001",
  "description": "Uganda order payment",
  "customer": {
    "name": "Jon Snow",
    "email": "ray.jon@mail.com",
    "phone": "+256775379021"
  }
}
```


## OpenAPI

````yaml POST /cross-border/collections/initiate
openapi: 3.0.0
info:
  title: NexaPay Business API
  version: 1.0.0
  description: Server-to-server merchant integration API documentation.
servers:
  - url: https://api.nexapay.ng/api/v1/business
    description: Production Server
security: []
tags: []
paths:
  /cross-border/collections/initiate:
    post:
      tags:
        - Cross-Border Collections
      summary: Initiate cross-border collection
      description: >-
        Starts a cross-border collection. For Kenya, this sends an M-Pesa
        collection request. For Uganda, this sends an MTN mobile money
        collection request. NexaPay locks the merchant NGN amount for instant
        credit after successful provider confirmation.
      parameters:
        - $ref: '#/components/parameters/BusinessEnvHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                businessId:
                  type: string
                reference:
                  type: string
                  description: >-
                    Optional merchant-supplied unique NexaPay transaction
                    reference.
                country:
                  type: string
                  example: UG
                currency:
                  type: string
                  example: UGX
                sourceCurrency:
                  type: string
                  example: UGX
                targetCurrency:
                  type: string
                  example: NGN
                amount:
                  type: number
                  example: 20000
                paymentMethod:
                  type: string
                  example: MTN
                merchantReference:
                  type: string
                  example: ORDER-UG-001
                description:
                  type: string
                  example: Uganda order payment
                customer:
                  type: object
                  properties:
                    name:
                      type: string
                      example: Jon Snow
                    email:
                      type: string
                      example: ray.jon@mail.com
                    phone:
                      type: string
                      example: '+256775379021'
                  required:
                    - name
                    - email
                    - phone
              required:
                - businessId
                - country
                - currency
                - amount
                - paymentMethod
                - customer
      responses:
        '201':
          description: Collection initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  msg:
                    type: string
                  collection:
                    type: object
                    properties:
                      transactionId:
                        type: string
                        example: NexaPay20260903140945570d4ed2170c3
                      reference:
                        type: string
                        example: NexaPay20260903140945570d4ed2170c3
                      merchantReference:
                        type: string
                        nullable: true
                        example: ORDER-TEST-001
                      status:
                        type: string
                        enum:
                          - PROCESSING
                          - COMPLETED
                          - FAILED
                          - PENDING_REVIEW
                        example: PROCESSING
                      sourceAmount:
                        type: number
                        example: 20000
                      sourceCurrency:
                        type: string
                        example: UGX
                      targetAmount:
                        type: number
                        example: 7200
                      targetCurrency:
                        type: string
                        example: NGN
                      rate:
                        type: number
                        example: 0.36
                      providerRate:
                        type: number
                        example: 0.4
                      provider:
                        type: string
                        example: brails
                      country:
                        type: string
                        example: UG
                      paymentMethod:
                        type: string
                        example: MTN
                      createdAt:
                        type: string
                        format: date-time
                      completedAt:
                        type: string
                        format: date-time
                        nullable: true
                      failedAt:
                        type: string
                        format: date-time
                        nullable: true
                      failureReason:
                        type: string
                        nullable: true
                  quote:
                    type: object
                    properties:
                      corridorKey:
                        type: string
                        example: UG_UGX_NGN
                      provider:
                        type: string
                        example: brails
                      country:
                        type: string
                        example: UG
                      sourceCurrency:
                        type: string
                        example: UGX
                      targetCurrency:
                        type: string
                        example: NGN
                      sourceAmount:
                        type: number
                        example: 20000
                      providerRate:
                        type: number
                        example: 0.4
                        description: Derived provider rate before NexaPay FX margin.
                      merchantRate:
                        type: number
                        example: 0.36
                        description: Rate shown to the merchant after NexaPay FX margin.
                      merchantReceives:
                        type: number
                        example: 7200
                        description: >-
                          NGN amount credited to the merchant after successful
                          payment confirmation.
                      markupType:
                        type: string
                        example: percentage
                      markupValue:
                        type: number
                        example: 10
                      rateSource:
                        type: string
                        example: sellRate
                      creditMode:
                        type: string
                        example: instant
                  providerResponse:
                    type: object
        '400':
          description: Invalid arguments or unsupported corridor/payment method.
        '409':
          description: Duplicate collection reference.
        '502':
          description: Provider failed to initialize collection.
      security:
        - ApiKeyAuth: []
components:
  parameters:
    BusinessEnvHeader:
      name: x-business-env
      in: header
      required: false
      schema:
        type: string
        enum:
          - prod
          - test
        default: prod
      description: Target environment selector (live production vs. simulated sandbox).
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Merchant API Key (e.g., nexa-prod-... or nexa-test-...)

````