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

# Créer un paiement

> Initiez une collecte ou un dépôt avec une clé d'idempotence.

Envoyez une clé `Idempotency-Key` stable pour la même opération métier. Une nouvelle clé crée une nouvelle opération.

```bash cURL theme={null}
curl --request POST \
  --url https://api.bizconnectpay.com/api/v1/payments \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-9481-collection' \
  --data '{
    "amount": "15000",
    "currency": "XAF",
    "country": "CM",
    "operation": "COLLECTION",
    "payment_method": "mtn_momo",
    "payer": {
      "phone_number": "+237671234567",
      "lang": "fr"
    },
    "description": "Paiement commande 9481",
    "metadata": {
      "client_reference": "CMD-2026-9481"
    }
  }'
```

```json Payload theme={null}
{
  "amount": "15000",
  "currency": "XAF",
  "country": "CM",
  "operation": "COLLECTION",
  "payment_method": "mtn_momo",
  "payer": {
    "phone_number": "+237671234567",
    "lang": "fr"
  },
  "description": "Paiement commande 9481",
  "metadata": {
    "client_reference": "CMD-2026-9481"
  }
}
```

```json 201 Created theme={null}
{
  "success": true,
  "data": {
    "id": "c5420e62-f80a-48a8-bec8-06eabf59e486",
    "reference": "BCP-PAY-01JAC8YMJ6",
    "account_id": "53258554-7e6a-4e8c-b213-a521430f83ce",
    "application_id": "56c21aef-170e-4941-a8da-e2aba353a42a",
    "country": "CM",
    "amount": "15000.0000",
    "currency": "XAF",
    "operation": "COLLECTION",
    "payment_method": "mtn_momo",
    "environment": "LIVE",
    "description": "Paiement commande 9481",
    "metadata": {
      "client_reference": "CMD-2026-9481"
    },
    "status": "PENDING",
    "expires_at": null,
    "created_at": "2026-10-20T12:30:00.000000Z",
    "updated_at": "2026-10-20T12:30:00.000000Z"
  },
  "meta": {
    "correlation_id": "9b76a47f-914b-46ab-a15a-19d8507aa589"
  }
}
```


## OpenAPI

````yaml openapi.json POST /payments
openapi: 3.1.0
info:
  title: BizConnectPay API
  version: 1.0.0
  description: >-
    API serveur-à-serveur pour les collectes, décaissements, transactions,
    remboursements, liens de paiement et cartes virtuelles.
servers:
  - url: https://api.bizconnectpay.com/api/v1
    description: Passerelle API BizConnectPay
security:
  - bearerAuth: []
tags:
  - name: Authentification
  - name: Services
  - name: Collectes
  - name: Transactions
  - name: Décaissements
  - name: Remboursements
  - name: Liens de paiement
  - name: Porteurs de carte
  - name: Cartes virtuelles
paths:
  /payments:
    post:
      tags:
        - Collectes
      summary: Initier une collecte
      description: >-
        Crée une intention de paiement et lance son orchestration asynchrone.
        Scope requis : `payments.write`.
      operationId: createPaymentIntent
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
            example:
              amount: '15000'
              currency: XAF
              country: CM
              operation: COLLECTION
              payment_method: mtn_momo
              payer:
                phone_number: '+237671234567'
                lang: fr
              description: Paiement commande 9481
              metadata:
                client_reference: CMD-2026-9481
      responses:
        '201':
          $ref: '#/components/responses/Created'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: Clé unique et stable pour cette opération métier.
      schema:
        type: string
        maxLength: 255
    CorrelationId:
      name: X-Correlation-ID
      in: header
      required: false
      schema:
        type: string
        format: uuid
  schemas:
    PaymentIntentRequest:
      type: object
      required:
        - country
        - amount
        - currency
        - operation
        - payment_method
        - payer
      properties:
        country:
          type: string
          minLength: 2
          maxLength: 2
          example: CM
        amount:
          type: string
          pattern: ^[0-9]+(\.[0-9]{1,4})?$
        currency:
          type: string
          minLength: 3
          maxLength: 3
          example: XAF
        operation:
          type: string
          enum:
            - COLLECTION
            - DEPOSIT
            - WITHDRAWAL
            - REFUND
            - TRANSFER
            - PAYOUT
            - REVERSAL
            - FX_CONVERSION
        payment_method:
          type: string
          maxLength: 60
        payer:
          type: object
          required:
            - phone_number
          properties:
            phone_number:
              type: string
              maxLength: 32
            otp_code:
              type:
                - string
                - 'null'
              maxLength: 32
            lang:
              type: string
              enum:
                - en
                - fr
        description:
          type:
            - string
            - 'null'
          maxLength: 1000
        metadata:
          type: object
          additionalProperties: true
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
    SuccessEnvelope:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data: {}
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorEnvelope:
      type: object
      properties:
        success:
          type: boolean
          const: false
        data:
          type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                message:
                  type: string
                details:
                  type:
                    - object
                    - array
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        correlation_id:
          type:
            - string
            - 'null'
          format: uuid
  responses:
    Created:
      description: Ressource créée
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessEnvelope'
    Unauthenticated:
      description: Authentification requise ou invalide
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: Scope ou état de compte insuffisant
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ValidationError:
      description: Payload ou règle métier invalide
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.