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

# One delivery and its trail

> The event, its payload and every attempt (`attempts_log`) with your server's status code, the first 1 KB of its answer and how long it took. Needs `read`.



## OpenAPI

````yaml /openapi.yaml get /v1/merchants/{merchantID}/webhook/deliveries/{id}
openapi: 3.1.0
info:
  title: CloudPay Core API
  version: 0.1.0
  summary: Wallet, ledger and payments API for CloudPay (Phase 0).
  description: >
    The Cloudpay money API: collect from phones and cards, pay out, and track
    every payment.


    Authenticate every request with your merchant API key: `Authorization:
    Bearer sk_test_...` (Development) or

    `sk_live_...` (Production). Keys can only move money and read payments;
    everything else is done signed in to

    the dashboard. Money is in cents (`1000` = KES 10.00). Every money request
    takes an `idempotency_key`.


    Guides, error codes and examples: https://cloudpay-africa.mintlify.site
  contact:
    name: CloudPay Engineering
servers:
  - url: https://api.cloudpay.africa/cloudpay
    description: Production and Development (the key chooses)
  - url: http://localhost:8080
    description: Local dev (make dev / make up)
security:
  - merchantKey: []
tags:
  - name: Merchant API
    description: >
      Run a business: tills, members and roles, balances, statements, sweeps,
      API keys. Authenticate as a member

      (bearer session; the role decides) or with a merchant API key
      (`Authorization: Bearer sk_...` or `X-Api-Key`).

      API keys reach only the money API (collections, disbursements, bulk,
      balances, statement, tills, fees, webhook

      deliveries, IPN addresses) with scopes read, collect, disburse; any other
      endpoint answers 403 api_key_not_allowed.
  - name: Merchant webhooks
    description: >
      Get told when a collection or payout finishes instead of polling. Set one
      HTTPS endpoint; CloudPay POSTs a signed

      event for every final status (`collection.completed|failed|review`,
      `disbursement.completed|failed|review`) and

      retries for about 38 hours. Every attempt is kept (the trail). Also lists
      the CloudPay IPN addresses to paste

      into a provider dashboard when you use your own Paystack keys.
  - name: Merchant rails
    description: >
      Merchant & developer API for payment rails (M-Pesa, SasaPay, Paystack):
      choose rails, bring your own keys,

      collect, disburse, bulk. Authenticate with a merchant API key
      (`Authorization: Bearer sk_...`) or a member's

      session plus `X-Merchant-ID`. Permissions: `read`, `collect`, `disburse`,
      `rails`, `credentials`.
paths:
  /v1/merchants/{merchantID}/webhook/deliveries/{id}:
    get:
      tags:
        - Merchant webhooks
      summary: One delivery and its trail
      description: >-
        The event, its payload and every attempt (`attempts_log`) with your
        server's status code, the first 1 KB of its answer and how long it took.
        Needs `read`.
      operationId: merchantWebhookTrail
      parameters:
        - $ref: '#/components/parameters/MerchantID'
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Delivery with attempts.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/WebhookTrail'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
      security:
        - merchantKey: []
components:
  parameters:
    MerchantID:
      name: merchantID
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    Envelope:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/Status'
    WebhookTrail:
      allOf:
        - $ref: '#/components/schemas/WebhookDelivery'
        - type: object
          properties:
            attempts_log:
              type: array
              items:
                type: object
                properties:
                  attempt:
                    type: integer
                  url:
                    type: string
                  response_status:
                    type: integer
                    nullable: true
                  response_body:
                    type: string
                  error:
                    type: string
                  duration_ms:
                    type: integer
                  at:
                    type: string
                    format: date-time
    Status:
      type: object
      required:
        - ok
        - code
        - desc
      properties:
        ok:
          type: boolean
        code:
          type: integer
        desc:
          type: string
    WebhookDelivery:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The event id; also sent as CloudPay-Event-Id. Dedupe on it.
        type:
          type: string
          example: collection.completed
        object_id:
          type: string
          format: uuid
          nullable: true
        status:
          type: string
          enum:
            - pending
            - sending
            - delivered
            - failed
        attempts:
          type: integer
        response_status:
          type: integer
          nullable: true
        error:
          type: string
        next_attempt_at:
          type: string
          format: date-time
        delivered_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        data:
          type: object
          description: >-
            The payment as it was when it finished (object, id, merchant_id,
            status, amount, fee, msisdn, reference, receipt, failure_reason,
            environment).
    ErrorEnvelope:
      type: object
      required:
        - status
        - errors
      properties:
        status:
          $ref: '#/components/schemas/Status'
        errors:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable machine-readable code.
          enum:
            - invalid_body
            - invalid_msisdn
            - invalid_purpose
            - invalid_device_id
            - invalid_amount
            - invalid_idempotency_key
            - invalid_reference
            - invalid_id
            - invalid_status
            - weak_pin
            - self_transfer
            - unauthorized
            - invalid_otp
            - invalid_pin
            - invalid_credentials
            - device_verification_required
            - party_blocked
            - not_allowed_for_tier
            - risk_denied
            - tenant_not_found
            - party_not_found
            - account_not_found
            - entry_not_found
            - topup_not_found
            - party_exists
            - idempotency_key_reused
            - entry_final
            - insufficient_funds
            - account_frozen
            - account_closed
            - account_locked
            - amount_below_minimum
            - amount_above_limit
            - daily_limit_reached
            - pin_locked
            - otp_rate_limited
            - invalid_kyc_tier
            - tenant_exists
            - balance_not_supported
            - live_mode_required
            - invalid_api_key
            - api_key_not_found
            - tenant_not_found
            - unauthorized
            - bootstrap_key_required
            - staff_key_required
            - staff_exists
            - staff_not_found
            - invalid_name
            - unknown_secret
            - secret_not_found
            - empty_value
            - unknown_provider
            - invalid_credentials
            - credential_not_found
            - invalid_public_key
            - reason_required
            - backup_not_found
            - self_approval
            - not_maker
            - backup_not_pending
            - backup_expired
            - backup_not_downloadable
            - internal
        message:
          type: string
  responses:
    Error:
      description: Error envelope. Branch on `errors.code`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            insufficient_funds:
              value:
                status:
                  ok: false
                  code: 422
                  desc: Unprocessable Entity
                errors:
                  code: insufficient_funds
                  message: insufficient funds
  securitySchemes:
    merchantKey:
      type: http
      scheme: bearer
      bearerFormat: sk_live_... / sk_test_...
      description: >-
        A merchant-scoped API key, issued by CloudPay staff or the merchant's
        owner. Acts with exactly its scopes.

````

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