{
  "openapi": "3.0.3",
  "info": {
    "title": "SenroPay merchant sandbox API",
    "version": "2026-10-19",
    "description": "Server-only scoped sandbox API using sp_hs_test_ bearer keys through the native SenroPay staging ingress. Payment/refund and M-Pesa collection contracts remain unchanged. Checkout uses Cloudflare Access and matching merchant or operations scope. A collection succeeds only when its authenticated query and retained callback agree. Collection return requests are review records; refund and reversal execution are unsupported. Production merchant access is not enabled."
  },
  "servers": [
    {
      "url": "https://merchant-api-staging.senropay.com/api/merchant/v1",
      "description": "Owned SenroPay staging API; approved sandbox merchants only"
    }
  ],
  "paths": {
    "/payments": {
      "post": {
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current saved resource, or idempotent replay",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "payment": {
                      "$ref": "#/components/schemas/Payment"
                    },
                    "replayed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Request saved; inspect resource status. A response is not confirmation of captured/refunded funds."
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "amount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100000000
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "KES",
                      "USD",
                      "EUR",
                      "GBP"
                    ]
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 160
                  }
                },
                "required": [
                  "amount",
                  "currency"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128
            }
          }
        ]
      }
    },
    "/payments/{payment_id}": {
      "get": {
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current saved resource, or idempotent replay",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "payment": {
                      "$ref": "#/components/schemas/Payment"
                    },
                    "replayed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{8,80}$"
            }
          }
        ]
      }
    },
    "/payments/{payment_id}/refunds": {
      "post": {
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current saved resource, or idempotent replay",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "refund": {
                      "$ref": "#/components/schemas/Refund"
                    },
                    "replayed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Request saved; inspect resource status. A response is not confirmation of captured/refunded funds."
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "amount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100000000
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 200
                  }
                },
                "required": [
                  "amount"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{8,80}$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128
            }
          }
        ]
      }
    },
    "/refunds/{refund_id}": {
      "get": {
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current saved resource, or idempotent replay",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "refund": {
                      "$ref": "#/components/schemas/Refund"
                    },
                    "replayed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "refund_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{8,80}$"
            }
          }
        ]
      }
    },
    "/collection-options": {
      "get": {
        "summary": "Read the currently approved masked payer and collection capability",
        "description": "",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionOptions"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/collections": {
      "get": {
        "summary": "List the newest 25 scoped collections",
        "description": "Use collections/search with next_cursor for subsequent pages.",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionPage"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create an expiring private checkout link",
        "description": "Persist the exact request and key. Merchant reference is unique per merchant. No arbitrary phone, callback or return URL is accepted. The approved payer and order terms are immutable.",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128,
              "pattern": "^[\\w:.\\-]{8,128}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionCreated"
                }
              }
            }
          },
          "201": {
            "description": "Collection intent saved; no provider prompt sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionCreated"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "amount": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 10000,
                    "multipleOf": 100
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "KES"
                    ]
                  },
                  "description": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 160
                  },
                  "merchant_reference": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{3,79}$"
                  },
                  "payer_id": {
                    "type": "string",
                    "pattern": "^dpp_[a-f0-9]{24}$"
                  },
                  "expires_in": {
                    "type": "integer",
                    "minimum": 300,
                    "maximum": 86400,
                    "default": 1800
                  }
                },
                "required": [
                  "amount",
                  "currency",
                  "description",
                  "merchant_reference",
                  "payer_id"
                ]
              }
            }
          }
        }
      }
    },
    "/collections/search": {
      "post": {
        "summary": "Read the next scoped collection page",
        "description": "",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128,
              "pattern": "^[\\w:.\\-]{8,128}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionPage"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "cursor": {
                    "type": "string",
                    "pattern": "^dci_[a-f0-9]{24}$"
                  }
                },
                "required": [
                  "cursor"
                ]
              }
            }
          }
        }
      }
    },
    "/collections/{collection_id}": {
      "get": {
        "summary": "Read saved collection status, checkout and recent return requests",
        "description": "A GET never calls a provider. The API key is scoped to one merchant. Read remains available during a processing pause.",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [
          {
            "name": "collection_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dci_[a-f0-9]{24}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionDetail"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/collections/{collection_id}/confirm": {
      "post": {
        "summary": "Confirm collection",
        "description": "Revalidate eligibility, payer, pricing and risk; reserve once before sending STK. Lost or ambiguous responses never authorize a replacement prompt. Retries recover the original.",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [
          {
            "name": "collection_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dci_[a-f0-9]{24}$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128,
              "pattern": "^[\\w:.\\-]{8,128}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionDetail"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {},
                "required": []
              }
            }
          }
        }
      }
    },
    "/collections/{collection_id}/sync": {
      "post": {
        "summary": "Sync collection",
        "description": "Query only the original request. Query calls have a 15-second cooldown. Missing acknowledgement blocks queries and requires operations investigation; no resubmission.",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [
          {
            "name": "collection_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dci_[a-f0-9]{24}$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128,
              "pattern": "^[\\w:.\\-]{8,128}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionDetail"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {},
                "required": []
              }
            }
          }
        }
      }
    },
    "/collections/{collection_id}/cancel": {
      "post": {
        "summary": "Cancel collection",
        "description": "Cancel an unused link. Submitted collections cannot be cancelled through this operation.",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [
          {
            "name": "collection_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dci_[a-f0-9]{24}$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128,
              "pattern": "^[\\w:.\\-]{8,128}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionDetail"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "reason": {
                    "type": "string",
                    "minLength": 10,
                    "maxLength": 500
                  }
                },
                "required": [
                  "reason"
                ]
              }
            }
          }
        }
      }
    },
    "/collections/{collection_id}/returns": {
      "post": {
        "summary": "Request product-specific refund or reversal review",
        "description": "Requires a refund-enabled key and matched successful collection. Open and capability-blocked requests cannot exceed the collection amount. This does not execute a refund/reversal, reserve ledger funds or mark money refunded.",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [
          {
            "name": "collection_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dci_[a-f0-9]{24}$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128,
              "pattern": "^[\\w:.\\-]{8,128}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionReturnResult"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "refund",
                      "reversal"
                    ]
                  },
                  "amount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10000
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 10,
                    "maxLength": 500
                  }
                },
                "required": [
                  "kind",
                  "amount",
                  "reason"
                ]
              }
            }
          }
        }
      }
    },
    "/collection-returns/{return_id}": {
      "get": {
        "summary": "Read the saved return review status",
        "description": "",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [
          {
            "name": "return_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dcr_[a-f0-9]{20}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionReturnResult"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/collection-returns/{return_id}/decision": {
      "post": {
        "summary": "Cancel the API key’s own pending return request",
        "description": "Only the original requester can cancel before independent review. Staff rejection/capability-block decisions use the signed-in console and separate reviewer. There is no execute endpoint.",
        "security": [
          {
            "MerchantKey": []
          }
        ],
        "parameters": [
          {
            "name": "return_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dcr_[a-f0-9]{20}$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128,
              "pattern": "^[\\w:.\\-]{8,128}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved current state; no inference of settled funds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionReturnResult"
                }
              }
            }
          },
          "default": {
            "description": "Error; 429 includes Retry-After. Retain the same idempotency key after timeouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "cancel"
                    ]
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 10,
                    "maxLength": 500
                  }
                },
                "required": [
                  "action",
                  "reason"
                ]
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "MerchantKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sp_hs_test_"
      }
    },
    "schemas": {
      "Payment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "merchant_id": {
            "type": "string"
          },
          "amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000000
          },
          "currency": {
            "type": "string",
            "enum": [
              "KES",
              "USD",
              "EUR",
              "GBP"
            ]
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "livemode": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "captured": {
            "type": "integer"
          },
          "refunded": {
            "type": "integer"
          },
          "checkout_url": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          }
        },
        "additionalProperties": false
      },
      "Refund": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "merchant_id": {
            "type": "string"
          },
          "amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000000
          },
          "currency": {
            "type": "string",
            "enum": [
              "KES",
              "USD",
              "EUR",
              "GBP"
            ]
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "livemode": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "payment_id": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "CollectionReturnCapability": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "product": {
            "type": "string",
            "enum": [
              "mpesa_stk_sandbox"
            ]
          },
          "requests_enabled": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "refund_execution": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "reversal_execution": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "product",
          "requests_enabled",
          "refund_execution",
          "reversal_execution",
          "reason"
        ]
      },
      "ApprovedCollectionPayer": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^dpp_[a-f0-9]{24}$"
          },
          "masked_phone": {
            "type": "string"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "masked_phone",
          "expires_at"
        ]
      },
      "Collection": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^dci_[a-f0-9]{24}$"
          },
          "merchant_id": {
            "type": "string"
          },
          "product": {
            "type": "string",
            "enum": [
              "mpesa_stk_sandbox"
            ]
          },
          "amount": {
            "type": "integer",
            "minimum": 100,
            "maximum": 10000,
            "multipleOf": 100
          },
          "currency": {
            "type": "string",
            "enum": [
              "KES"
            ]
          },
          "description": {
            "type": "string"
          },
          "merchant_reference": {
            "type": "string"
          },
          "payer": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string"
              },
              "masked_phone": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "masked_phone"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "awaiting_confirmation",
              "processing",
              "succeeded",
              "failed",
              "needs_review",
              "expired",
              "cancelled"
            ]
          },
          "submitted": {
            "type": "boolean"
          },
          "can_query": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "livemode": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "settlement_status": {
            "type": "string",
            "enum": [
              "separate_review_required"
            ]
          },
          "return_capability": {
            "$ref": "#/components/schemas/CollectionReturnCapability"
          }
        },
        "required": [
          "id",
          "merchant_id",
          "product",
          "amount",
          "currency",
          "merchant_reference",
          "status",
          "livemode"
        ]
      },
      "CollectionReturn": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^dcr_[a-f0-9]{20}$"
          },
          "collection_id": {
            "type": "string"
          },
          "merchant_id": {
            "type": "string"
          },
          "product": {
            "type": "string",
            "enum": [
              "mpesa_stk_sandbox"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "refund",
              "reversal"
            ]
          },
          "amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000
          },
          "currency": {
            "type": "string",
            "enum": [
              "KES"
            ]
          },
          "reason": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending_review",
              "blocked_unsupported",
              "rejected",
              "cancelled"
            ]
          },
          "decision_reason": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "decided_at": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "execution_enabled": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "livemode": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "id",
          "collection_id",
          "kind",
          "amount",
          "currency",
          "status",
          "execution_enabled",
          "livemode"
        ]
      },
      "CollectionOptions": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "merchant": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "currency": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name",
              "currency"
            ]
          },
          "product": {
            "type": "string",
            "enum": [
              "mpesa_stk_sandbox"
            ]
          },
          "currency": {
            "type": "string",
            "enum": [
              "KES"
            ]
          },
          "min_amount": {
            "type": "integer"
          },
          "max_amount": {
            "type": "integer"
          },
          "payer": {
            "type": "object",
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/ApprovedCollectionPayer"
              }
            ]
          },
          "can_create": {
            "type": "boolean"
          },
          "can_review": {
            "type": "boolean"
          },
          "blocked_reason": {
            "type": "string"
          },
          "return_capability": {
            "$ref": "#/components/schemas/CollectionReturnCapability"
          },
          "livemode": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": []
      },
      "CollectionPage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "collections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Collection"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "collections",
          "total",
          "next_cursor"
        ]
      },
      "CollectionDetail": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "collection": {
            "$ref": "#/components/schemas/Collection"
          },
          "checkout_url": {
            "type": "string",
            "format": "uri"
          },
          "can_confirm": {
            "type": "boolean"
          },
          "can_sync": {
            "type": "boolean"
          },
          "can_cancel": {
            "type": "boolean"
          },
          "returns": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CollectionReturn"
            }
          },
          "returns_truncated": {
            "type": "boolean"
          }
        },
        "required": []
      },
      "CollectionCreated": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "collection": {
            "$ref": "#/components/schemas/Collection"
          },
          "checkout_url": {
            "type": "string",
            "format": "uri"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": []
      },
      "CollectionReturnResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "return_request": {
            "$ref": "#/components/schemas/CollectionReturn"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "return_request"
        ]
      }
    }
  },
  "x-collection-notifications": {
    "api_version": "2026-10-19",
    "types": [
      "collection.updated",
      "collection_return.updated"
    ],
    "delivery": "At least once, durable event ID, HMAC-SHA256. Fetch current state before order decisions; events can arrive out of order. Collection success requires query/callback agreement; reviewed settlement is separate. Return requests are not refunded funds."
  },
  "x-senropay-documentation": {
    "environment": "sandbox",
    "production_available": false,
    "transport": "native-owned-ingress",
    "api_base": "https://merchant-api-staging.senropay.com/api/merchant/v1"
  }
}
